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READ ME FIRST 


All computer software is subject to change, correction, or improvement as the 
manufacturer receives customer comments and experiences. Radio Shack has 
established a system to keep you immediately informed of any reported prob¬ 
lems with this software, and the solutions. We have a customer service network 
including representatives in many Radio Shack Computer Centers, and a large 
group in Fort Worth, Texas, to help with any specific errors you may find in 
your use of the programs. We will also furnish information on any improve¬ 
ments or changes that are “cut in’’ on later production versions. 


To take advantage of these services, you must do three things: 

(1) Send in the postage-paid software registration card included in this manual 
immediately. (Postage must be affixed in Canada.) 

(2) If you change your address, you must send us a change of address card 
(enclosed), listing your old address exactly as it is currently on file with us. 

(3) As we furnish updates or “patches”, and you update your software, you 
must keep an accurate record of the current version numbers bn the logs 

" -^elow^She version number will be furnished with each update. 

* n 

Keep this card in your manual at all times, and refer to the current version 

numbers when requesting information or help from us. Thank you. 


APPLICATIONS SOFTWARE 
VERSION LOG 


OP. SYSTEM 
VERSION LOG 
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TERMS AND CONDITIONS OF SALE AND LICENSE OF RADIO SHACK COMPUTER EQUIPMENT AND SOFTWARE 
PURCHASED FROM A RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL STORE OR FROM A 
RADIO SHACK FRANCHISEE OR DEALER AT ITS AUTHORIZED LOCATION 


LIMITED WARRANTY 



I. CUSTOMER OBLIGATIONS 

A. CUSTOMER assumes full responsibility that this Radio Shack computer hardware purchased (the “Equipment”), and any copies of Radio 
Shack software included with the Equipment or licensed separately (the “Software”) meets the specifications, capacity, capabilities, 
versatility, and other requirements of CUSTOMER 

B. CUSTOMER assumes full responsibility for the condition and effectiveness of the operating environment in which the Equipment and Software 
are to function, and for its installation 

II. RADIO SHACK LIMITED WARRANTIES AND CONDITIONS OF SALE 

A. For a period of ninety (90) calendar days from the date of the Radio Shack sales document received upon purchase of the Equipment, RADIO 
SHACK warrants to the original CUSTOMER that the Equipment and the medium upon which the Software is stored is free from manufacturing 
defects THIS WARRANTY IS ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT BY THE ORIGINAL CUSTOMER FROM 
RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, RETAIL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS 
AUTHORIZED LOCATION. The warranty is void if the Equipment’s case or cabinet has been opened, or if the Equipment or Software has been 
subjected to improper or abnormal use. If a manufacturing defect is discovered during the stated warranty period, the defective Equipment 
must be returned to a Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or Radio Shack dealer 
for repair, along with a copy of the sales document or lease agreement. The original CUSTOMER’S sole and exclusive remedy in the event of 
a defect is limited to the correction of the defect by repair, replacement, or refund of the purchase price, at RADIO SHACK’S election and sole 
expense. RADIO SHACK has no obligation to replace or repair expendable items. 

B. RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of the Software, except as provided in this 
paragraph. Software is licensed on an “AS IS” basis, without warranty. The original CUSTOMER’S exclusive remedy, in the event of a 
Software manufacturing defect, is its repair or replacement within thirty (30) calendar days of the date of the Radio Shack sales document 
received upon license of the Software. The defective Software shall be returned to a Radio Shack Computer Center, a Radio Shack retail store, 
participating Radio Shack franchisee or Radio Shack dealer along with the sales document. 

C. Except as provided herein no employee, agent, franchisee, dealer or other person is authorized to give any warranties of any nature on behalf 
Of RADIO SHACK. 

D Except as provided herein, RADIO SHACK MAKES NO WARRANTIES, INCLUDING WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 
PARTICULAR PURPOSE. 

E. Some states do not allow limitations on how long an implied warranty lasts, so the above limitation(s) may not apply to CUSTOMER. 

III. LIMITATION OF LIABILITY 

A. EXCEPT AS PROVIDED HEREIN. RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY TO CUSTOMER OR ANY OTHER PERSON 
OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY 
“EQUIPMENT” OR “SOFTWARE” SOLD, LEASED, LICENSED OR FURNISHED BY RADIO SHACK, INCLUDING, BUT NOT LIMITED TO, ANY 
INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE 
USE OR OPERATION OF THE “EQUIPMENT” OR “SOFTWARE” IN NO EVENT SHALL RADIO SHACK BE LIABLE FDR LOSS OF PROFITS, OR 
ANY INDIRECT. SPECIAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER 
ARISING OUT OF OR CONNECTED WITH THE SALE, LEASE, LICENSE, USE OR ANTICIPATED USE OF THE “EQUIPMENT” OR “SOFTWARE” 

NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK’S LIABILITY HEREUNDER FOR DAMAGES INCURRED BY 
CUSTOMER OR OTHERS SHALL NOT EXCEED THE AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR “EQUIPMENT” OR “SOFTWARE” 
INVOLVED. 

B. RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing Equipment and/or Software. 

C. No action arising out of any claimed breach of this Warranty or transactions under this Warranty may be brought more than two (2) years 

after the cause of action has accrued or more than four (4) years after the date of the Radio Shack sales document for the Equipment or 

Software, whichever first occurs. 

D. Some states do not allow the limitation or exclusion of incidental or consequential damages, so the above limitation(s) or exclusion(s) may 
not apply to CUSTOMER. 

IV. RADIO SHACK SOFTWARE LICENSE 

RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the RADIO SHACK Software on one computer, subject to the following 

provisions: 

A Except as otherwise provided in this Software License, applicable copyright laws shall apply to the Software. 

B. Title to the medium on which the Software is recorded (cassette and/or diskette) or stored (ROM) is transferred to CUSTOMER, but not title to 

the Software. 

C. CUSTOMER may use Software on one host computer and access that Software through one or more terminals if the Software permits this 
function. 

D. CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on one computer and as is specifically 
provided in this Software License. Customer is expressly prohibited from disassembling the Software. 

E. CUSTOMER is permitted to make additional copies of the Software only for backup or archival purposes or if additional copies are required in 
the operation of one computer with the Software, but only to the extent the Software allows a backup copy to be made. However, for 
TRSDOS Software, CUSTOMER is permitted to make a limited number of additional copies for CUSTOMER’S own use. 

F. CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has purchased one copy of the Software for each 
one sold or distributed. The provisions of this Software License shall also be applicable to third parties receiving copies of the Software from 
CUSTOMER. 

G. All copyright notices shall be retained on all copies of the Software. 

V. APPLICABILITY OF WARRANTY 

A. The terms and conditions of this Warranty are applicable as between RADIO SHACK and CUSTOMER to either a sale of the Equipment and/or 
Software License to CUSTOMER or to a transaction whereby RADIO SHACK sells or conveys such Equipment to a third party for lease to 
CUSTOMER. 

B. The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO SHACK, the author, owner and/or licensor of the 
Software and any manufacturer of the Equipment sold by RADIO SHACK. 

VI. STATE LAW RIGHTS 

The warranties granted herein give the original CUSTOMER specific legal rights, and the original CUSTOMER may have other rights which vary 

from state to state. 


~ Jim 




... 
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The FCC Wants You to Know... 

This equipment generates and uses radio frequency energy. If not installed and used prop¬ 
erly, that is, in strict accordance with the manufacturer’s instructions, it may cause interfer¬ 
ence to radio and television reception. 

It has been type tested and found to comply with the limits for a Class B computing 
device in accordance with the specifications in Subpart J of Part 15 of FCC Rules, which are 
designed to provide reasonable protection against such interference in a residential instal¬ 
lation. However, there is no guarantee that interference will not occur in a particular 
installation. 

If this equipment does cause interference to radio or television reception, which can be 
determined by turning the equipment off and on, the user is encouraged to try to correct the 
interference by one or more of the following measures: 

• Reorient the receiving antenna 

• Relocate the computer with respect to the receiver 

• Move the computer away from the receiver 

• Plug the computer into a different outlet so that computer and receiver are on different 
branch circuits. 

If necessary, you should consult the dealer or an experienced radio/television technician for 
additional suggestions. You may find the following booklet prepared by the Federal Com¬ 
munications Commission helpful: How to Identify and Resolve Radio-TV Interference 
Problems. 

This booklet is available from the US Government Printing Office, Washington, DC 
20402, Stock No. 004-000-00345-4. 

Warning 

This equipment has been certified to comply with the limits for a Class B computing device, 
pursuant to Subpart J of Part 15 of FCC Rules. Only peripherals (computer input/output 
devices, terminals, printers, etc.) certified to comply with the Class B limits may be attached 
to this computer. Operation with non-certified peripherals is likely to result in interference to 
radio and TV reception. 
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All Rights Reserved. Licensed to Tandy Corporation. 
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this manual to assure its accuracy, Tandy Corporation and Logical 
Systems assumes no liability resulting from any errors or omissions in 
this manual, or from the use of the information contained herein. 
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Introduction 


About the Model 4 

Congratulations on the purchase of your TRSDOS Model 4 Disk 
System. Your new Model 4 is a compact desktop computer that is 
perfect for business needs, as well as personal use. You will find it to 
be a valuable tool which will save you work as well as give you hours 
of enjoyment. Its basic features include: 

• 65536 characters of random access memory, expandable to 128K 

• High-speed Z-80 microprocessor, the “brains” of the computer 

• Upper and lower case text display of 80 characters by 24 lines or 
64 by 16 (software selectable) 

• Compatible with Radio Shack’s Model III Software Library. 

• One or two built-in drives that let you use single-sided, 
double-density floppy disks. 

• Sound generation. 

• 70-key console keyboard which includes three function keys and 
numeric keypad. 

• Built in printer interface. 

As your needs grow — you can expand your Model 4 to include hard 
disks, external floppy disk drives, high-resolution graphics, printers, 
RS-232C communications and more. 




About This Manual 


This manual shows how you can use your disk system to: 

• Store, retrieve or manipulate information on disk (using TRSDOS). 

• Write programs for Model 4 (using BASIC). 

The Model 4’s operating system is TRSDOS Version 6. Throughout 
this manual, we refer to this system simply as TRSDOS. 

In the Introduction To Your Disk System manual, we covered all the 
essential information to get you started. As you learn more about 
TRSDOS and programming, you can take advantage of its many 
features explained in this manual. 

Since this is a reference manual, you don’t have to read it from front 
to back. If you are a programmer, you’ll find a lot of useful information 
in this manual. If you are an advanced programmer, you’ll find 
additional “advanced” information included for you in this manual. 
Additional technical information is available in The Technical 
Reference Manual (Cat. No. 26-2110). This manual is available at 
your local Radio Shack store. 

Part 1/ TRSDOS 

Section 1/ Using TRSDOS describes how to start up 
TRSDOS, what TRSDOS Ready means, and some general 
information on how TRSDOS works. 

Section 11/ TRSDOS Commands contains a number of 
commands and utilities you will find helpful. 

PART 11/ BASIC 

Section III/ Operations explains how to start up and 
operate BASIC. 

Section IV/ BASIC Language describes (1) BASIC 
concepts, (2) how to store data on disks, and (3) each 
BASIC statement and function. 




Table of Contents 





Page 


Introduction 

About The Model 4. i 

About This Manual. ii 

Part 1/ TRSDOS 

Section 1/ Using TRSDOS.1-3 

How the Computer Uses TRSDOS.1-5 

TRSDOS Notations.1-5 

TRSDOS Terms.1-5 

TRSDOS Abbreviations.1-6 

Loading TRSDOS.1-6 

TRSDOS Ready.1-6 

Executing a Command.1-7 

Disk Files.1-7 

Devices.1-10 

Section 11/ TRSDOS Commands.1-11 

Introduction.1-13 

How to Use This Section.1-14 

Syntax.1-15 

Part 11/ Basic 

Introduction to BASIC 

About This Manual.2-3 

Notations.2-3 

Terms.2-4 

Terms Used in Chapter 7 for Brevity.2-4 

Section III/ Operations.2-7 

Chapter 1/ Sample Session.2-9 

Chapter 2/ Command And Execution Section.2-13 

Chapter 3/ Line Edit Mode.2-17 

Section IV/ BASIC Language.2-23 

Chapter 4/ BASIC Concepts.2-25 

Chapter 5/ Disk Files.2-51 

Chapter 6/ Introduction To BASIC Statements 

And Functions.2-59 

Chapter 7/ BASIC Statements 

And Functions.2-65 

Part III/ Appendices.A-1 

Appendix A/ Job Control Language.A-3 

Simple JCL Execution.A-4 

Simple JCL Compiling.A-12 

Advanced JCL Compiling.A-25 

Using TRSDOS JCL To Interface With 

Applications Programs.A-30 

Practical Examples Of TRSDOS JCL Files.A-33 

Appendix B/ Model 4 Hardware 

Keyboard Code Map.A-35 

Specifications.A-39 


iii 











































Appendix C/ Character Codes.A-45 

Appendix D/ Error Messages and Problems 

In Case Of Difficulty.A-61 

TRSDOS.A-63 

BASIC.A-69 

Appendix E/ Converting TRSDOS Version 1 Programs to 

TRSDOS Version 6 BASIC Programs.A-75 

Appendix F/ BASIC Keywords and Derived Functions 

Reserved BASIC Words.A-79 

Internal Codes for BASIC Keywords.A-80 

Derived BASIC Functions.A-82 

Appendix G/ BASIC Worksheets 

Video. A-83 

Appendix H/ Glossary.A-85 

Appendix 1/ TRSDOS Programs.A-91 

Appendix J/ BASIC Memory Map.A-101 

Appendix K/ Using The Device-Related Commands.A-103 

Appendix \J HERZ50.A-107 

Appendix M/ Backup Limited Diskettes.A-109 




iv 



















ADDENDUM 


TRSDOS Version 6.1.2 


Contents 

Introduction .1 

Backing Up Your Master Diskette .2 

Upgrading Version 6.0 Diskettes ...3 

Upgrading Version 6.1.0 and 6.1.1 Diskettes .7 

New BASIC Features for Versions 6.1.1, 6.1.0, and 6.0 ....8 
Improvements for Versions 6.1.1, 6.1.0, and 6.0 .12 

r*V 

Improvements for Versions 6.1.0 and 6.0 


26 








Addendum 


TRSDOS Version 6.1.2 


Introduction 


TRSDOS Version 6.1.2 contains several improvements and some 
new features that supercede previous versions of TRSDOS for 
Models 4 and 4P. To take advantage of these improvements, 
upgrade all of your diskettes, including data and 
apllication program diskettes, to TRSDOS Version 6.1.2. 

The label on your original master diskette indicates the 
version. If your system is presently running under TRSDOS 
Version 6.0, 6.1.0, or 6.1.1, use the appropriate procedure 

to upgrade your diskettes. Repeat this procedure for each 
diskette. 

Before you upgrade any of your diskettes, follow the 
instructions in Chapter 3 of your Introduction To Your Disk 
System manual or see the section "Making a Backup of your 
Master Diskette" to make a backup of the Version 6.1.2 
master diskette. Make two copies of the master diskette in 
case you make an error during the conversion procedures. 

After you upgrade your diskettes, do not use the previous 
version TRSDOS diskettes. Always use the Version 6.1.2 
diskettes. If you have no other use for the earlier version 
diskettes, you can reformat and reuse them for Version 
6 . 1 . 2 . 

Upgrading your diskettes to Version 6.1.2 requires two 
drives. If you do not have two disk drives, check with your 
Radio Shack dealer to locate a two-drive system that you can 
use to upgrade your diskettes. 
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TRSDOS Version 6.1.2 



Backing Op Your Master TRSDOS 6.1.2 Diskette 


1. Insert your TRSDOS 6.1.2 master diskette into Drive 0 
and a blank diskette into Drive 1. Close the drive door and 
press the reset button. 

2. At the TRSDOS Ready prompt, type: 

FORMAT :1 <Q=N) <ENTER> 

When formatting is complete, TRSDOS displays the message: 
Formatting complete 
TRSDOS Ready 

If TRSDOS displays an error message, repeat Steps 1 and 2. 

3. Type: 


BACKUP :0 :1 <ENTER> 

W 

The system displays the prompt: 


Destination disk ID is different: NAME=DATADISK 
Date=mm/dd/yy 

Are you sure you want to backup to it <Y,N> ? 

4. Press <YXENTER>. When the backup is complete, TRSDOS 
displays the message: 


Backup complete 
TRSDOS Ready 


5. Remove the diskettes. Put your original TRSDOS 6.1.2 
diskette in a safe place and use the copy from now on. Make 
two copies of the master diskette in case you make an error 
during the conversion procedures. 
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Upgrading Version 6.0 diskettes to Version 6.1.2 


Upgrading System Diskettes 

To copy programs or files from your Version 6.0 system 
diskette to your new Version 6.1.2 diskette, follow these 
steps: 

1. Insert a write-enabled copy of a Version 6.1.2 diskette 
in Drive 0 and your Version 6.0 diskette in Drive 1. Press 
the reset button to start up the system under Version 6.1.2. 


2. At the TRSDOS Ready prompt, type: 

BACKUP :1 :0 (NEW,INV) <ENTER> 

This command copies programs and files to the Version 6.1.2 
diskette. 

When the backup is complete, TRSDOS displays the message: 
Backup complete 
TRSDOS Ready 

If TRSDOS displays a "Disk is full" message, see the next 
section "Error Handling." 

3. Remove the diskette from Drive 0 and label it to 
indicate that it contains the same files as the diskette in 
Drive 1. You should make a backup of the new diskette to 
protect your programs and files. 


Error Handling 

1. If TRSDOS displays the message: 

Disk is full! - Enter new formatted destination disk 
<ENTER> 

press <BREAK>. 


3 




Addendum 


TRSDOS Version 6.1.2 


'a. At the TRSDOS Ready prompt, type: 

PURGE -BACKUP/CMD:0 (Q=N,INV) <ENTER> 

deletes all files except BACKUP and the operating system 
from the diskette in Drive 0. The diskette in Drive 0 no 
longer contains all of the files that are on your master 
Version 6.1.2 diskette. Try the backup again by typing: 

BACKUP :1 :0 (NEW,INV) <ENTER> 

When BACKUP is complete, TRSDOS displays the "Backup 
complete" message. Proceed to Step 3. 

2b. If TRSDOS displays the "Disk is full!" message again, 
display the names of all files that are on both diskettes. 

To do this, press <BREAK> and type: 

DIR <ENTER> 

Use the PURGE command to delete from the Drive 0 diskette, 
all files that are not on the Drive 1 diskette. After you 
PURGE these files, type: 

BACKUP :1 :0 (NEW,INV) <ENTER> 

When the backup is complete, TRSDOS displays the "Backup 
complete" message. If TRSDOS displays the "Disk is full!" 
message again contact your Radio Shack dealer. Otherwise, 
proceed with Step 3. 

3. After you successfully copy all files from the Version 
6.0 diskette, remove the Version 6.0 diskette from Drive 1. 
Insert a copy of your master Version 6.1.2 system diskette 
in Drive 1. To ensure that all of the old system is 
replaced on the diskette in Drive 0, type: 

BACKUP :1 :0 (OLD,SYS,INV) <ENTER> 

4. When TRSDOS displays the "Backup complete" message, 
remove the diskette from Drive 0 and label it to indicate 
that it contains the same files as the diskette in Drive 1. 
You should make a backup of the new diskette to protect your 
programs and files. 
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Upgrading Version 6.0 Data Diskettes 


1. Insert a TRSDOS 6.1.2 diskette in Drive 0 and a blank 
diskette into Drive 1. Close the drive doors. Press the 
reset button. 

2. At the TRSDOS Ready prompt, type: 

FORMAT :1 (Q=N) <ENTER> 

When formatting is complete, TRSDOS displays the message: 
Formatting complete 
TRSDOS Ready 

If there are any flawed tracks, use a different diskette and 
repeat Steps 1 and 2. 

3. Type: 

BACKUP :0 :1 (X) <ENTER> 

TRSDOS displays the message: 

Insert SOURCE diskette <ENTER> 

Remove the TRSDOS 6.1.2 diskette from Drive 0 and insert the 
data diskette that you want to upgrade. 

4. Press <ENTER>. TRSDOS displays the message: 

Insert SYSTEM diskette <ENTER> 

Remove the TRSDOS 6.0 diskette from Drive 0 and insert the 
TRSDOS 6.1.2 system diskette. Press <ENTER>. When backup 
is complete, TRSDOS displays the message: 

Backup complete 

TRSDOS Ready 

Note: If TRSDOS does not display this message, repeat 
Steps 3 and 4. If the problem persists, your Version 
6.0 diskette contains flaws. Use the COPY command to 
copy each file from your Version 6.0 diskette to your 
Version 6.1.2 diskette. 
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After you successfully copy all files from the Version 6.0 
diskette, remove the Version 6.1.2 diskette and label it to 
indicate that it is a Version 6.1.2 data diskette that 
contains the same information that is on the Version 6.0 
data diskette. To protect your data, make a backup of the 
Version 6.1.2 data diskette. 
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Upgrading all Version 6.1.0 and Version 6.1.1 

Use this procedure to upgrade Version 6.1.0 and 6.1.1 
system, data, and application diskettes. 

1. Insert a write-enabled copy of a Version 6.1.2 diskette 
in Drive 0 and your Version 6.1.0 diskette into Drive 1. 
Close the drive doors. Press the reset button to start up 
the system under Version 6.1.2. 

2. At the TRSDOS Ready prompt, type: 

BACKUP :0 :1 (OLD,SYS,INV) <ENTER> 

TRSDOS displays the message: 

Backup by class invoked 

When the backup is complete, TRSDOS displays the message: 
Backup complete 
TRSDOS Ready 
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New BASIC Features for Versions 6.1.1, 6.1.0, and 6.0 
Integer Division 

The backslash (\) is the symbol for integer division. BASIC 
rounds both operands to integers and truncates the result to 
an integer. 

Examples 

PRINT 10 \ 4 

prints 2. 

PRINT 68 \ 6.99 

prints 9. 


Modulus Arithmetic 

MOD is the operator for modulus arithmetic. BASIC rounds 
both operands to integers. The result is the integer that 
is the remainder of an integer division. 

Examples 

PRINT 10 MOD 3 

prints 1. Ten divided by 3 is 3 with a remainder of 1. 
PRINT 68 MOD 6.99 

prints 5. 68 divided by 7 is 3 with a remainder of 5. 
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Additional Logical Operators 


Version 6.1.2 contains two additional logical operators, EQV 
and IMP. Add the following to the logical operators table 
in "Chapter 4/BASIC Concepts." 


Operator 


Meaning of 
Operation 


First Second 
Operand Operand Result 


EQV 


If both bits 1 1 
are 1 or both 1 0 
bits are 0, the 0 1 
result is 1. 0 0 


1 

0 

0 

1 


IMP 


The result is 1 1 
unless the first 1 
bit is 1 and the 0 
second bit is 0. 0 


1 

0 

1 

0 


1 

0 

1 

1 
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WIDTH 


Function 


WIDTH [LPRINT] size 


Sets the line width (number of characters per line) for the 
display or line printer. If you omit the LPRINT option, 
BASIC sets the screen width. 

size is an integer in the range 15 to 255 that specifies 
the number of characters in a line. If you omit size , 

BASIC assumes 80 for the display or 255 for the printer. 

If size is 255, the printer width is infinite. That is, 
BASIC never inserts a carriage return. However, after 
printing the 255th character, LPOS and POS return a value of 
0 . 

Note: If you are using the TRSDOS program FORMS/FLT, set 
printer width at 255. 

If you execute a WIDTH statement to change the width of the 
screen or printer, execute another WIDTH statement to 
restore the width to its default values before your 
program ends execution. 

When width is set less than the default values, BASIC issues 
a carriage return after printing every size character. 

BASIC does not separate the characters in a string unless 
the string is longer than the total width of the screen. 

For example: 


10 WIDTH 18 

20 PRINT "ABCDEFGHIJKLMNOPQRSTUVWXYZ";”1234567890" 
RUN 


displays: 

ABCDEFGHIJKLMNOPQR 
STUVWXYZ1234567890 
Ready 
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After printing 18 characters of the string, BASIC issues a 
carriage return and prints the remaining characters in the 
first string. BASIC checks to see if there are enough 
positions left in the current line to print the second 
string. If there are, it prints the second string. 

If a string contains fewer characters than the width but 
there are not enough positions remaining on the current 
line, BASIC prints the string on the next line. BASIC 
separates the characters in a string only when the cursor is 
in the first column. For example: 

10 WIDTH 18 

20 PRINT "-ABCDEFGHIJKLMNOPQRSTUVWXYZ-";"-1234567890-" 
RUN 

displays: 

-ABCDEFGHIJKLMNOPQ 
RSTUVWXYZ- 
-1234567890- 
Ready 

Before printing the first string, BASIC checks to see if 
there are enough positions remaining on the current line to 
print the entire string. The string contains 28 characters 
and the screen width is only 18. If the cursor is in Column 
1, BASIC prints the portion of the string that fits on the 
line. It then issues a carriage return and prints the 
remaining characters on the next line. BASIC checks to see 
if there are enough positions left on the line to print the 
second string. There are only nine positions left on the 
current line and the second string contains 12 characters. 
BASIC issues a carriage return before printing the second 
string. 

Example 





10 WIDTH 20 

20 PRINT "Jane Doe";"Tandy Center";"Fort Worth, Tx" 

displays: 

Jane Doe 
Tandy Center 
Fort Worth, Tx 
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Improvements for Versions 6.1.1, 6.1.0, and 6.0 
BOOT Command 

When you use one or more of the keys, you must press and 
hold them down when the screen is erased and keep them down 
until the TRSDOS Ready prompt or the DEBUG display appears. 
If you are prompted for the date, enter the date and then 
hold down the keys. If you don't press the keys in time, 
simply reset the system and hold the keys down as soon as 
the screen clears. 

On the Model 4P, pressing <ENTER> has a special meaning 
during the start up procedure. To allow no breakable AUTO 
commands to occur, you must press <ENTER> after typing BOOT, 
release <ENTER>, and press <ENTER> again. 


DEBUG Command 
Command Descriptions 

When the DEBUG monitor is displayed, you can enter one of 
the following single-key commands. 

You must enter all numerics, addresses and quantities, as 
hexadecimal values. If you make a mistake entering these 
hexadecimal values, simply type the correct value before you 
press the space bar. DEBUG ignores the incorrect address 
because it ignores all but the last four digits in an 
address and all but the last two digits of a byte. For 
example, if you want to enter some data at Address 6789 and 
you type 6780, type the correct address before you press 
the space bar, as shown here: 

H67806789 <SPACE BAR> 


12 


Addendum 


TRSDOS Version 6.1.2 


A (ASCII Modify) 

Aaddress 

Enter the above command to modify address. If the 
contents of address are already on the display, vertical 
bars appear around the byte being modified. 

After you enter address , press the space bar. The address 
and its contents appear in the lower left corner of the 
screen. To modify the byte, type the new character. DEBUG 

moves to the next byte and allows you to modify it. 

In addition to typing a new character, you may also press: 

<SPACE BAR> to retain the value of the current address 
and move to the next address. 

<ENTER> to exit from the A command. 

Note: You cannot use the X command to cancel an 
incorrect A command after you enter an address to 
modify. If you press <X> after you enter an address, 
DEBUG stores the character X at the current address. 
Instead, use <ENTER> to exit the A command. 

To store an ASCII space character (X'20') or a carriage 
return (X'OD') use the H command and enter a '20' or a '0D' 
at the address of the space. 

If you do not specify address , TRSDOS uses the current 
"memory modification address" (shown by the vertical bars). 

Example 

AD004 <SPACE BAR> 

displays D004 and the character stored at D004 in the lower 
left corner of the screen. Type the new character. Press 
<ENTER> to exit from the A command or more characters to 
change the next addresses. 
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Extended Command Descriptions 
Additional information for the N command: 


The load block type byte is the byte at the beginning of 
each block. Before using this command, position the 
vertical bars over the load block type byte. To do this, 
use the H command by typing: 

H address <ENTER> 

COPY command 

Additional information for the COPY command: 


When you update a file, use COPY to make a duplicate file on 
another disk. This protects you from having to reenter the 
entire file if the disk gets damaged. 

Use COPY to reduce file fragmentation. File fragmentation 
exists when there is not enough contiguous space on a disk 
to store the file. TRSDOS uses small areas of the disk 
where they are available. Fragmentation increases the 
amount of time required to access the data in the file. To 
reduce fragmentation, COPY the file to a disk that has 
enough contiguous space for the file. The FREE command 
displays the amount of free space on a disk. (See FREE and 
DIR for more information on file fragmentation.) 


CREATE command 

Additional information for the CREATE command: 

The smallest unit of space TRSDOS allocates for a file is 
one granule. A granule is one or more 256 byte sectors. 

The size of a granule varies depending on the type of disk 
you are using. Double-sided diskettes contain six 256-byte 
sectors or 1.5 K bytes in a granule. Use the FREE command 
to see the size of disk granules. See the FREE command for 
more infromation. 
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If a file requires more than one granule, but fewer than two 
granules, TRSDOS allocates 2 granules. TRSDOS cannot 
allocate a portion of a granule. To determine the number of 
granules TRSDOS allocates for a file of a specific length, 
use this formula for double density diskettes: 


(LRL * REC / 256) / 6 or SIZE / 1.5 


FILTERS 

When resetting filters and devices, reset the primary device 
and then the filter device. Resetting the filter device 
before the primary device can scramble the system device 
table. 


FORMAT utility 

Additional information for the FORMAT utility: 

If you specify an invalid drive number, TRSDOS displays an 
"Illegal drive number" error message. 

If there is a write-protect tab on the disk or if the drive 
is protected by the SYSTEM (DRIVE=,WP) command, TRSDOS 
displays a "Disk write protected" error message. 

If TRSDOS displays the error message "Load destination 
diskette" after you insert the destination diskette: 

1. Be sure the disk drive door is closed. 

2. Be sure that the diskette is inserted correctly. 

3. If the drive is an external drive, be sure the 
drive is connected and plugged into the outlet. 

4. Try formatting the disk in a different drive. 

If TRSDOS does not display the message "Formatting 
complete," repeat the format. If TRSDOS still does not 
display the message, the disk is flawed. Try using another 
disk. 
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FORMS command 

Additional information for the FORMS command: 

FFHARD allows the printer to manage top-of-form. Most 
printers that support top-of-form have a control that must 
be set to the length of the paper for FFHARD to function 
properly. The default for this control is usually 66 lines- 
per-page. Not all printers support top-of-form. Check your 
printer owner's manual for more information on top-of-form 
control. 

Using FFHARD is faster than sending a series of line feeds. 
If you are using the system spooler, FFHARD requires less 
space in memory and on disk. See the SPOOL command. 


LINK command 

Additional information for the LINK command: 

Suppose you want your computer to be accessed by another 
computer or terminal. If your computer is at the office you 
can use a remote terminal as the keyboard and display of 
your Model 4. First, set the Communications Line device 
(*CL) and use SETCOM to specify W0RD=8 and PARITY=NO. 

Do this by entering these commands: 

SET *CL TO COM/DVR <ENTER> 

SETCOM (W0RD=8,PARITY=NO) <ENTER> 

Now link the video display and keyboards to the RS-232C 
interface, by typing : 

LINK *D0 *CL 
LINK *KI *CL 

This lets your Model 4 act as "host" and be accessed by a 
remote terminal via the RS-232C hardware. 

While these links are in place, all keyboard input from the 
Model 4 keyboard or the remote terminal keyboard is treated 
as if it originated from the Model 4 keyboard. Text 
displayed on the Model 4 screen is transmitted to the remote 
terminal. 

Note: Some programs display data using a direct 
access method. This data is not displayed on the 
remote terminal. For more information about direct 
access, see the §VDCTL SVC in the Model 4/4P Technical 
Reference Manual. 
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SPOOL command 

Additional information for the SPOOL command: 

Some application programs do not support HIGH$ and write 
over a portion of the SPOOL program. When this occurs, 
TRSDOS displays the error message "Can't locate SPOOL in 
memory." In the future do not use that application program 
with SPOOL. 

If you issue a SPOOL (OFF) command when SPOOL is already 
off, TRSDOS displays the error message "Spool is not 
active." If you attempt to change the parameters of SPOOL 
after SPOOL is active, TRSDOS displays the error message 
"Spool is already active." You must turn SPOOL off and turn 
it back on with the new parameters. 

If after loading SPOOL, you load another program that uses 
high memory, TRSDOS may not be able to release memory it is 
using and displays the error message "Can't reclaim memory 
space." You must reset the system if you need the space. 

If you attempt to use Banks 1 or 2 on a 64K system or if you 
request a bank that is already in use, TRSDOS issues the 
error message "Requested bank in use." 

If there isn't enough memory available to set up the routes 
that the spooler uses, TRSDOS issues the error message "No 
memory space available." Remove any logical devices that 
you aren't using. 

The driver that is connected to the devspec specified in a 
SPOOL command must be an output device driver. If you 
specify an input device TRSDOS issues the error message 
"Device driver incompatible." 
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Improvements for BASIC in Version 6.1.2 
INPUT and LINE INPUT Statements 

The syntax description for INPUT and LINE INPUT statements 
in "Section II/ BASIC For Version 6 Reference Manual" 
contain an error. 

INPUT 

The correct syntax for the INPUT statement is: 

INPUT [" prompt string; "] variablel, variable2,... 

You may not specify a semicolon (;) immediately after INPUT 
to suppress carriage returns that are part of the response. 



LINE INPUT 

The correct syntax for the LINE INPUT statement is: 

LINE INPUT [" prompt message ";] string variable 

You may not specify a semicolon (;) immediately after LINE 
INPUT to suppress carriage returns that are part of the 
response. 
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Appendix A/Job Control Language 


There is an error in the the section "Using TRSDOS JCL To 
Interface With Applications Programs." 

To execute a JCL file once you enter BASIC, the correct 
command format is: 

SYSTEM"DO filename " 

You can type this command directly or enter it as a BASIC 
program line. 

Also, if you call a JCL file from BASIC, the file should 
contain the //EXIT termination macro, so that control 
returns to the TRSDOS Ready prompt when the JCL file is 
complete. 

For example, suppose you want to use the JCL //ALERT macro 
to inform you of the completion of a lengthy BASIC 
procedure. Following the lines containing the BASIC 
procedure, you could have a BASIC program line such as: 

1000 SYSTEM "DO = ALERT/JCL:0" 

that executes the ALERT/JCL file: 

.Your procedure is complete. Press <ENTER> to resume. 
//ALERT (1,0,7,0) 

BASIC 

//STOP 

When BASIC reaches Line 1000, the JCL file ALERT/JCL is 
executed, sending a series of repeating tones to the tone 
generator. 

You are notified that your BASIC procedure is complete. 
Pressing <ENTER> ends the JCL alert and returns you to 
BASIC. 

This example invloves two important points. First, the 
comment line in the ALERT/JCL file is necessary, as a JCL 
file cannot start with an execution macro. Second, the 
BASIC statement reloads BASIC. If you want a particular 
program to load and run, you can place its name on the 
command line or add the BASIC commands before the //STOP 
statement. You must include the //STOP termination macro to 
assure that keyboard control remains within BASIC. 
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Appendix C/Character Codes 

Additional explanation for Decimal Control Code 21 and 22 

Code 21 toggles the video driver between space compression 
codes and the special/alternate character set. Code 22 
toggles the video driver between the special character set 
and the alternate character set. The setting of the toggle 
controlled by Code 21 determines if the Code 22 toggle has 
any effect on what is displayed. 

The following chart illustrates the power-up and first 
toggle states for Codes 21 and 22: 


Code 21 


Power-up state space compression 

characters 

First toggle state special/alternate 

characters 

At power-up, codes in the range 192 to 255 produce one or 
more spaces (space compression mode). From this point, you 
can enter the special character set by outputting a Code 21 
to the display. You can then enter the alternate character 
set by outputting a Code 22 to the display. To switch back 
to the special set, output another Code 22. To switch back 
to space compression codes from either the special or 
alternate character set, output a Code 21. 

When the system is in space compression mode, outputting a 
Code 22 still toggles between special and alternate 
character sets, even though it does not affect the 
characters subsequently displayed. Any characters in the 
range 192 to 255 that are already on the display toggle 
between special and alternate character sets each time the 
display receives a Code 22. 

Note: Special and alternate characters are not 
available if you enable reverse video (Code 16). 


Code 22 


special 

characters 

alternate 

characters 
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Appendix D/Error Messages 

and Problems 

Additional BASIC Messages 

for Version 6.1.2 


68 Disk write protected The drive number you specified 

is write-protected. Either 


69 File access DENIED 

the write-protect notch is 
covered on the diskette or 
the diskette was write 
protected with the TRSDOS 

SYSTEM (DRIVE=n,WP) command. 

The file you attempted to 
access is password protected. 

Specify the exact password to 
gain access to the file. 

70 Command Aborted 

The command specified in a 

SYSTEM statement was aborted. 

You either pressed <BREAK> -— 

during the execution of a 
library command or tried to 
execute a program or utility. 

Only library commands can be 
executed with the SYSTEM 
statement. 




21 



Addendum 


TRSDOS Version 6.1.2 


Appendix F/ BASIC Keywords and Derived Function 

There are additional reserved words in Version 6.1.2. Add 
these to the list of reserved words in Appendix F: 

EQV IMP WIDTH XOR 
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rs 


Appendix J/ Memory Maps 


TRSDOS Memory Map 


0000H to 25FFH 

2600H to 2FFFH 


3000H to HIGH$ 


HIGH$ to FFFFH 


Operating System Reserved for 

TRSDOS operations. 


Overlay Area 


All library commands 
and some utilities 
use this area. If 
BASIC or other 
programs use this 
area, you must not 
allow SYSTEM 
commands (through 
the use of the 
@CMNDR SVC) or you 
must reload this 
area when the SVC 
returns. 


User Program 


Driver/Filter 
/User or System 
Tasks 


Reserved for 
application 
programs. 

Reserved for 
system drivers, 
filters, and tasks 
that cannot fit into 
the area reserved in 
TRSDOS. TRSDOS 
stores MEMDISK in 
this area when it 
resides in Bank 0. 


HIGH$ is a pointer that TRSDOS maintains. It moves 
depending on the number and size of modules stored above the 
address that HIGH$ points at. You can use the MEMORY 
command to display or to alter the value of HIGH$. 
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0000H to 25FFH 


2600H to 2FFFH 


3000H to 80FFH 

8100H to Bottom 
of Stack 


Bottom of Stack 
to HIGH$ or Top- 
of-Memory you 
define with M 
parameter when 
you start BASIC 


Top-of-memory (M) 
or HIGH$ to HIGH$ 


BASIC Memory Map 


Operating System 
Overlay Area 


BASIC 

BASIC program 


BASIC Stack and 
File Control 
Block(s) 


Assembly language 
routines called 
from BASIC 


Reserved for TRSDOS 
operations. 

Used alternately by 
TRSDOS and BASIC. 
When you use a 
SYSTEM "" command, 
TRSDOS uses this 
area to store the 
program that 
performs the 
command. BASIC 
reloads this area 
with its data when 
you return to 
TRSDOS. 

Reserved for BASIC. 

Reserved for your 
program, variables, 
strings, and arrays. 

Contains the stack 
that BASIC and the 
File Control 
Block(s) (FCB) use. 
Each FCB requires 
564 bytes of 
storage. The number 
of open files you 
select with F 
parameter when you 
start BASIC 
determines the 
number of FCBs. 

BASIC reserves an 
additional FCB for 
its own use. 

This area exists 
only if you define 
it with the M 
parameter when you 
start BASIC. 
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HIGH$ to FFFFH Driver/Filter/ 

User or System 
tasks 


This area stores 
drivers, filters, 
and tasks that the 
system uses. This 
includes the 
spooler, Memdisk 
(when it resides in 
Bank 0), and the 
drivers and filters 
that cannot fit into 
the area TRSDOS 
reserves. To place 
assembly language 
routines in this 
area, see the 
restrictions in the 
Model 4/4P 

Technical 

Reference 

Manual. 


Programs 

Your program space is dynamic. It depends on the number of 
data files you request when loading BASIC (concurrent 
files), the HIGH$ marker, the amount of stack space, and the 
highest memory location you specify when loading BASIC. For 
more information on loading BASIC, see Chapter 1. 

If the HIGH$ marker is at the top of physical memory (FFFFH) 
and you do not set the highest memory location BASIC can use 
(with the M parameter), there is 31 K bytes of memory 
available for your program. Each concurrent files uses 564 
bytes of memory. 

If HIGH$ is not at FFFFH, or if you specify the M parameter 
when loading BASIC, use the PRINT FRE(O) command to display 
the amount of program space available. 

The number of concurrent files also determines the location 
of the top of the stack. BASIC uses this formula: 

location = M - (564 x number of concurrent files ) - 564 

Location is the top of the stack. You can use the CLEAR 
statement to set aside additional stack space. Additional 
stack space decreases the amount of program space available. 
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Improvements and New Features for Versions 6.0 and 6.1.0 


Using More Than Two Disk Drives 

In Version 6.1.2, TRSDOS assumes you have two disk drives. 
This causes TRSDOS to start up and locate files faster than 
previous versions. However, if you have more than two disk 
drives you need to apply some patches to make TRSDOS aware 
of the additional drives. 

To apply these patches, insert a write-enabled Version 6.1.2 
diskette in Drive 0. Press the reset button to start up 
under Version 6.1.2. If you have three drives, only apply 
the first patch. If you have four drives, apply both 
patches. 


Patch 1 

At the TRSDOS Ready prompt, type: 

PATCH BOOT/SYS.LSIDOS:0 (D02,84=C3:F02,84=C9) 


Patch 2 

At the TRSDOS Ready prompt, type: 

PATCH BOOT/SYS.LSIDOS:0 (D02,8E=C3:F02,8E=C9) 
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SYSTEM command 

On version 6.1.2, the SYSTEM command has a new parameter, 
STEP. STEP sets the rate in milliseconds (msec) at which 
the computer accesses the disk drives. 

In Version 6.1.2, the step rate is 6 milliseconds, rather 
than 12 msec, as on previous versions. Model 4P does not 
operate at 12 msec. Model 4 owners can use the SYSTEM 
(STEP=) command to change the step rate. 

STEP= number sets the rate at which the computer accesses 
the drive. Number may be in the range 0 to 3 and 
represents the following access rate in milliseconds: 

Number Milliseconds 

0 6 

1 12 

2 20 

3 30 

The step rate remains in effect until the system is 
re-booted, turned off or SYSGENed. 
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MODELA/III 

Your Version 6.1.2 diskette contains the file "MODELA/III." 
Only Model 4P owners who wish to run in Model III mode need 
this file. Model 4 owners may remove this file. Model 4P 
owners should refer to Introduction to Your Disk System 
for additional information. 


BACKUP 

Backup Reconstruct. The system performs a backup 
reconstuct when the size or density differs between source 
and destination disks. 

DIR/SYS and BOOT/SYS do not move to the destination disk in 
this type of backup. 

When you specify a backup by class or a backup reconstruct, 
BACKUP moves only the types of files you specify. (This is 
a departure from the Model III hard disk operating system, 
LDOS 5.1.3.) For example, if Drive 2 is a hard disk, the 
command: 

BACKUP :5 :2 

moves visible files to the hard disk. BACKUP performs a 
backup reconstruct because the two disks are different 
sizes. 

BACKUP :5 :2 (SYS,INV) 

moves all files (visible, invisible, and system files) to 
the destination disk. 

Hard disk users should note that TRSDOS stores the system 
files in specific places in the directory. If you use 
BACKUP to move the visible files and then repeat the command 
with the SYS option, the backup aborts if the visible files 
use the specific directory positions that system files 
require. If this happens, use the PURGE command to delete 
the visible files, and then execute a BACKUP command with 
the SYS option. 
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VERIFY 

In Versions 6.0 and 6.1.0 the switches for the VERIFY 
command were erroneously documented as YES and NO. The 
switches are ON and OFF. 


Examples 

VERIFY (ON) <ENTER> 
turns on the verify function. 

VERIFY (OFF) <ENTER> 
turns off the verify function. 
VERIFY <ENTER> 

turns on the verify function. 
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Improvements and New Features for Version 6.0 only 


Date Prompt 


In Version 6.1.2, the date prompt when booting your system 
is: 

Date MM/DD/YY ? 


Diskettes 

We recommend that you format new diskettes using Version 
6.1.2 and use BACKUP to copy your programs and data from the 
Version 6.0 diskette to a Version 6.1.2 diskette. See Page 
5 for more information on upgrading data diskettes. 

You can reformat the Version 6.0 diskettes and reuse them. 
You may find that cylinders that were flawed using Version 
6.0 are not flawed using Version 6.1.2 FORMAT. 

Version 6.1.2 now supports single density diskettes. 

In Version 6.1.2, FORMAT has been greatly improved over 
FORMAT for Version 6.0. In Version 6.0, FORMAT has 
difficulty formatting cylinders past Cylinder 22. FORMAT 
indicates flawed cylinders that aren't flawed. In addition, 
the data stored on cylinders beyond Cylinder 22 deteriorates 
faster than normal. 


Using Filters 


When you use more tha 

n one filter or driver in Version 6.0, 

only the FORMS filter can move from low memory to high 
memory. In Version 6.1.2, all filters and drivers, except 
Memdisk, can move into high memory when all of low memory 
has been used. If the filter or driver moves into high 
memory, TRSDOS displays messages similar to: 

Note: driver installed in high memory 


or 

Note: filter installed in high memory 


Note: When using Memdisk with any other filters or 
drivers, you should start Memdisk first to ensure that 
Memdisk is in low memory. 
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When disabling Memdisk with Version 6.0, you may have 
encountered some problems with the operating system. 

Version 6.1.2 remedies these problems. 


Stack Usage 

In Version 6.0, TRSDOS uses the same stack as application 
programs use. If an application program places the stack at 
an address above X'F3FF', TRSDOS cannot access memory above 
that address while displaying text or reading the keyboard. 

In Version 6.1.2, TRSDOS uses its own stack, which it keeps 
in low memory. This removes the X'F3FF' restriction, 
leaving more memory available for programs. 

PATCH command 

In Version 6.0, the L patch command does not function 
properly. Version 6.1.2 remedies any problems you may have 
had with this command. 


m 
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SYSTEM command 

On version 6.1.2, the SYSTEM command has a new parameter, 
RESTORE. To use RESTORE, you must have a write-enabled 
diskette in Drive 0. The syntax is: 

SYSTEM (RESTORE= switch ) 

switch may be YES or NO. TRSDOS assumes RESTORE=YES. 

RESTORE=YES causes all enabled floppy drives to move the 
read/write head to Cylinder 0 when booting the system. This 
eliminates some of the drive noise and some of the delay 
when you are using a drive for the first time. RESTORE=YES 
increases the length of time when booting. 

RESTORE=NO disables RESTORE 


HERTZ/ JCL 

Your Version 6.0 diskette contains the file "HERTZ50/JCL" to 
patch TRSDOS to run properly in areas that have 50 Hertz 
(Hz) electrical power. Your Version 6.1.2 diskette contains 
the file "HERTZ/JCL," which functions similarly to the 
Version 6.0 file. However, the HERTZ/JCL allows you to 
specify which power source you are using. 

Your hardware must have been modified before you apply this 
patch. To apply this patch, type (at the TRSDOS Ready 
prompt): 

DO = HERTZ 

HERTZ/JCL displays a few messages and prompts you to enter 5 
if your hardware is configured for 50 Hz, or 6 if your 
hardware is configured for 60 Hz. 

After you apply this patch to your system, you must press 
the reset button to put the change into effect. 
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Technical Information for Version 6.0 


In Version 6.0, the @BREAK Supervisor Call (SVC 103) does 
not function properly. This causes problems with certain 
library commands. The problem is remedied in Version 6.1.2. 

If the printer is not ready in Version 6.1.2, the Forms 
filter stops after 10 seconds when performing a form-feed. 

In Version 6.0, the Forms filter stops after waiting 11 
minutes. 

In Version 6.0, application programs can change the cursor 
character. However, the application cannot return the 
cursor to its default value. Version 6.1.2 remedies this 
problem. 


875-9436 
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Section 1/ Using TRSDOS 


S-> 

How The Computer Uses TRSDOS 

Whenever you are using a program which runs under TRSDOS, your 
computer will, from time to time, need to reference TRSDOS. It 
always looks for TRSDOS on Drive 0. 

For this reason, you must at all times have TRSDOS in Drive 0. 


TRSDOS Notations 

For clarity and brevity, we use some special notations and type styles 
in this section. 

CAPITALS and punctuation 

indicates material that you must enter exactly as it appears or 
material that you see on your computer’s video display. 

(KEYBOARD CHARACTER) 

indicates key you press. 

italics 

represents words, letters, characters, or values that you supply. 



TRSDOS Terms 


Below is a listing of terms which we use frequently in this section. The 
italicized words represent variable information which you must supply. 

command represents the TRSDOS command you want to 

execute, command can be in upper or lowercase 
letters. 


(parameters) 


filespec 


devspec 


diskette 

disk 


is a list of one or more values that may be needed 
by the command. Some commands have no 
parameters. Most parameters are optional. 
Brackets [ ] around any word in a command line 
indicate that it is optional. 

is a standard TRSDOS file specification having the 
general form: 

filename! ext.password: drive 

is (1) one of six standard TRSDOS device 
specifications, or (2) a user created device 
specification having the general form: 

*two-letter abbreviation 

refers exclusively to a floppy diskette. 

refers to a floppy diskette. 
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disk ID 


refers to the disk NAME, creation date, and 
Master Password. 

refers to a transfer of data (Input/Output). 


I/O 


TRSDOS Abbreviations 


You can abbreviate a parameter to its first letter (unless otherwise 
stated in the command explanation). You can also abbreviate YES to 
Y and NO to N. 


Loading TRSDOS 


When you install and power up your system, you’ll see the TRSDOS 
start-up logo. This means you’re in the TRSDOS Version 6 Operating 
System. You then need to enter the current date in the form 
mmlddlyy. For example, for June, 14, 1983, type: 

06 / 14/83 (ENTER) 

The system displays the date in expanded form (for example, Tue, 
Jun 14, 1983). 




TRSDOS Ready 


Whenever you see the TRSDOS Ready prompt you know that you 
are in control of TRSDOS — not COBOL, PAYROLL, or any of your 
application programs. Being in control of TRSDOS allows you to do 
one of these operations: 

• execute a TRSDOS system command or utility program 

• execute an application program 

When an error occurs, it came from one of two places: TRSDOS or 
the application program that you are running. If it came from 
TRSDOS, look in Appendix D or the TRSDOS command section for 
an explanation of the error message. If it came from the application 
program that is running, you’ll need to see the manual which came 
with the application program for an explanation of the error message 


r 
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Executing A Command 

You can execute a TRSDOS system command whenever you see the 
TRSDOS Ready prompt. The command you type can consist of up to 
79 upper or lower case characters. You must enter the command by 
pressing (ENTER) . 

For example, if you want to see the TRSDOS system commands, 
type: 

LIB (ENTER) 


TRSDOS displays a list of all the available system commands and 
returns to TRSDOS Ready: 


Lib rary <A> 


Append Copy 

Device 

Dir 

Do 

Filter 

Lib 

Link List 

Route Run 

Load 

Set 

Memory 

Remove 

Rename 

Reset 

Lib rary <B> 

Attrib Auto 
Free Purse 

Build 

Time 

Create 

Verify 

Date 

Debus 

Dump 

Library <C> 

Fo rms Setcom 

Se tk i 

Spoo 1 

Sys Sen 

System 



If you wanted this display to print on the screen, type (CTRL)m . 
Whenever you press this key sequence, what is displayed on the 
screen is printed on the printer. 


Disk Files 



You can keep a record of anything you type into your Model 4 by 
storing it on disk in a “disk file.” A disk file can contain a program, a 
collection of data, a project report you intend to make, or almost 
anything you want it to contain. But whatever it is, if you want to keep 
it permanently, you’ll have to store it in a disk file. 

When the computer stores the file, it records the name of the file and 
its disk location in a special place on the disk called the disk’s 
directory. Whenever you want to access the file, the computer can 
immediately find its location by using this directory. 

Filespec 

Whenever you create a disk file, you need to give it a name. This 
name is just one part of a file specification — filespec, for short. The 
filespec is the standard TRSDOS format you’ll use every time you 
reference your file: 

filer) am e/exttpassuordi drive 
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filename 

The name of your file can be most anything you like, as long as it is 
one to eight alphanumeric characters, the first of which must be a 
letter. (The only names you cannot use are TO, ON, USING and 
OVFR.) 

/extension 

If you want to further identify your file, you can give it a second name 
by adding an extension. An extension (indicated by /ext on our 
filespec) is a sequence of one to three alphanumeric characters (the 
first of which must be a letter) with a preceding slash (/). 

You can use an extension to provide additional information on a file, 
or you can use an extension to indicate the type of file you have. 

.password 

A password protects a file by limiting access to it. You can 
accomplish this protection via a password either when you create the 
file or with the ATTRIB command. 

A password is a sequence of up to eight alphanumeric characters, the 
first of which must be a letter. 

:drive 

Often when you’re using your computer, you’ll have more than one 
disk drive in use. You can speed up the file access time by specifying 
the drive the desired file is on. 

If you omit a drive number on the filespec, your computer 
automatically starts looking for the file on all available drives, 
beginning with Drive 0. 

Here are some examples of valid TRSDOS filespecs: 

DOPROG.OPEN 
CLR/BAS:1 
MODI 6:4 

STL12/TXT.ARCH:1 

GAME1 

THESIS/OLD :2 
CONTEMPT 


You cannot use TO, ON, OVER, or USING as TRSDOS filespecs. 


Partspecs 

Certain system commands and utilities allow you to specify a 
collection of files by using a “partspec.” A partspec is used with a 
“wildcard” mask ($). When you use a wildcard in a partspec, it 
represents a wildcard field and means “any character.” For example, 
suppose the following files exist on a disk in Drive 1: 
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A 

ADVANCE/DAT 
ADVERTISE 
BILL ING/CMD 
BILLING/BAK 

If you issue the command: 

DIR A: 1 (ENTER) 

TRSDOS displays these files: 

A 

ADVANCE/DAT 

ADVERTISE 


ACORN 

ADVISE/DAT 

BILLING 

BILLING/DAT 


ACORN 

ADVISE/DAT 


All files on the disk that begin with the letter A are displayed because 
when you specify a partspec, TRSDOS treats the command as “DIR 
of all files that begin with ‘A’.” 

If you issue the command: 

DIR BILLING: 1 (ENTER) 

TRSDOS displays: 

BILLING BILLING/CMD 

BILLING/DAT BILLING/BAK 

Because you did not specify an extension, TRSDOS assumed that all 
extensions are acceptable. 

If you issue the command: 

DIR /$A : 1 (ENTER) 

TRSDOS displays the files on the disk which have an A as the 
second character in their extension: 


ADVANCE/DAT ADVISE/DAT 

BILLING/DAT BILLING/BAK 


Because you did not specify a filename, TRSDOS assumed that all 
filenames are acceptable. 

A wildcard character must always have at least one character to its 
right. The following partspecs are identical: 


A A$ 

A$$$ A$/$ 

A$/*$$ 
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Devices 



There are two kinds of TRSDOS devices: physical and logical. 

A physical device is a piece of your computer hardware: the video 
display, the keyboard, the printer, etc. 

A logical device (devspec) is a connection between TRSDOS and a 
physical device. 

TRSDOS lets you treat your devices independently, which means you 
can sometimes substitute a device for another one. You can also 
substitute a file for a device. See the LINK, ROUTE, and SET library 
commands. 

Devspec 

When you want to access a device, you use its device specification or 
devspec. 

TRSDOS devices already have devspecs assigned to them. You 
assign devspecs to devices that you create. The devspec is the 
standard TRSDOS format you’ll use every time you reference your 
device: 

*two-letter abbreviation 

Your original TRSDOS master diskette is configured with six devices. 
They are: 


Devspec 

Device 

*KI 

Keyboard Input 

*DO 

Display Output (Video) 

*PR 

Printer 

*SI 

Standard Input 

*so 

Standard Output 

*JL 

Job Log 


Drivers And Filters 

Each device is controlled by its own driver program, filter program, or 
both. You can change a device’s I/O by manipulating its driver or filter 
program. For more information on drivers and filters see the SET and 
FILTER commands; see also Appendices I and K. 
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Section II/ TRSDOS Commands 







Section II/ TRSDOS Commands 


TRSDOS commands and utilities (typed in at the TRSDOS Ready 
level) perform a variety of helpful operations: 

Diskette Handling commands allow you to prepare your blank 
diskettes for use or make copies of existing diskettes. Any time you 
use a blank diskette, you should use this command: 

FORMAT 

If you want to change the way your computer system starts up and 
initializes its parameters, you can use Initialization commands. For 
example, you can use the FORMS commands to set your printer’s 
parameters; or you can use the AUTO command to set your computer 
to AUTOmatically perform a particular function at start-up. The 
Initialization commands are: 

AUTO 
DATE 
SETCOM 
SYSGEN 
TIME 

You might find the Auxiliary commands helpful for such functions as 
seeing what is on your disk or simply seeing what system commands 
are available. They include: 

DEVICE 
DO 
LIB 
LOG 
VERIFY 

The File Handling commands and utilities allow you to copy, rename, 
delete, or convert your disk files. These commands include: 


APPEND 

ATTRIB 

BACKUP 

BUILD 

COMM 

CONV 

COPY 

CREATE 

DEBUG 

PATCH 

PURGE 

REMOVE 

RENAME 

REPAIR 

TAPE100 



The Device Handling commands allow you to set, filter, route, or 
reset your devices. Be sure you have a good understanding of 
devices before you use these commands! These commands include: 

FILTER LINK 

MEMDISK RESET 

ROUTE SET 

Machine Language File Handling commands create and execute 
machine language disk files. These commands include: 


DIR 

FREE 

LIST 

SPOOL 


BOOT 

FORMS 

SETKI 

SYSTEM 
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DUMP 

MEMORY 


LOAD 

RUN 




How to Use This Section 

This section contains an alphabetic listing of all TRSDOS commands 
and utilities. The commands and utilities for advanced programmers 
are marked as “Advanced Programmer’s Utilities” and “Advanced 
Programmer’s Commands.” 

Commands 

Commands are system operations that can be used at TRSDOS 
Ready. 

To see a list of all library commands, use the LIB command. Type: 
LIB (ENTER) 

and the following list is displayed: 

Library <A> 

Append Copy 
Link List 
Route Run 

Library <B> 

Att rib Auto 
Free P u r * e 

Library <C> 

Forms Setcom SetKi Spool Sysaen System 

Utilities 

Utilities use some or all of user memory. They return to TRSDOS 
Ready; under most conditions you cannot use them effectively within 
programs. 

The utilities are: 

BACKUP COMM 

CONV FORMAT 

LOG PATCH 

REPAIR 


Device Dir Do Filter Lib 

Load Memory Remove Rename Reset 
Set 


Build Create Date D e b u $ Dump 

Time Verify 


r\ 
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Entry Organization 

Each entry in this section is identified as either a command or a utility. 

The command’s “syntax” is the first line you see after the keyword. 
Use it as your guide to type in a command. (See “Syntax” below for 
details.) If a word or value in the syntax is highlighted, you need to 
type in that word or value for the command to work. 

A description of the command or utility follows the syntax. This 
description tells you what the command or utility does. Next, the entry 
includes additional information on the parameters of the command. A 
command may require you to supply some values. 

The definition also may offer several “options” that customize the 
command to your needs. These optional parameters increase the 
usefulness of the commands but are not necessary for normal 
operation. Values and options are discussed in the additional 
parameter information. 

Finally, each entry gives examples of the command’s use. 


Syntax 



The command’s syntax tells you what format to use when you type 
the command. 

For example, here is the syntax for the REMOVE command: 
REMOVE filespec, filespec ... 

italicized words in a command’s syntax indicate values that you 
supply. In this case, the value that you supply is a filename. 
Remember that a command’s required parameters are highlighted, 
so the beginner can skip values not boldfaced. 

If you want to remove the disk file named SAMPLE in Drive 1, type: 

REMOVE SAMPLE ; 1 (ENTER) 

The syntax for the COPY command is: 

COPY source [TO] destination [(parameters)] 

Here, you must supply the name of the source filespec you wish to 
copy and the destination filespec to which you want it copied. 
Remember that TO is optional and cannot be used as a TRSDOS 
filespec. For example: 

COPY NEW/DAT: i TO NEUDAT/ONE : 2 (ENTER) 

copies the Drive 1 file NEW/DAT onto the diskette in Drive 2 and 
names the new file NEWDAT/ONE. 

The COPY command offers four optional parameters. They are: 
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LRL 

CLONE 

ECHO 

X 

If you need the LRL parameter (the LRL parameter tells TRSDOS to 
assign a specific record length to a destination filespec), type: 

COPY NEW/DAT : 1 TO NEWDAT/ONE : 2 (LRL = 128) (ENTER) 

Every command uses some variation of the syntax lines discussed 
above. 




1-16 






APPEND 


Command 

APPEND source [TO] destination [{parameters)] 



Appends the contents of the source onto the end of the contents of 
the destination. (The contents of the source file remain the same.) 

You can use APPEND to combine two files on a disk. 

The source is a valid TRSDOS filespec or input devspec, and 
destination is a valid TRSDOS filespec. 

The parameters are: 

ECHO echoes the characters to the screen when appending a 
device to a file. 

STRIP backspaces the destination file one byte before the 
append begins. Use this parameter with files, such as 
SCRIPSIT files, that have an “internal end of file marker.” 

Examples 

APPEND EAST/DAT: 1 TO NEST/DAT: 0 (ENTER) 

adds the information in EAST/DAT on Drive 1 onto the end of the 
information in WEST/DAT on Drive 0. 


APPEND *K I TO NEST/DAT: 0 (ENTER) 


appends the information that you type on the keyboard to the end of 
WEST/DAT on Drive 0. Press (C0NTR0L)($HIFT)(W) (at the same time) 
to end the append. 

APPEND *K I TO WEST/DAT: 0 (ECHO) (ENTER) 


displays what yo u are appending to WEST/DAT as you type it. 
) (SHIFT) ((5D (at the same time) to end the append. 


ffiWW . 


Press 


Error Conditions 


If the records in source and destination are not the same length, then 
an error message appears. 


APPEND is mainly for data files since it works only with files 
containing ASCII text. You cannot APPEND program files that are in 
the “load module format.” Also, you cannot APPEND BASIC 
programs unless they are saved in the ASCII format. 

Some programs (such as SCRIPSIT) place a special marker at the 
end of a file. If this marker is in the file, you must use the STRIP 
parameter when appending to it. If you do not use the STRIP 
parameter, the program ignores the appended section of the file. 
Consider the following example: 
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APPEND EAST/DAT: 1 TO WEST/DAT:0 (STRIP) (ENTER) 

copies the information from EAST/DAT to WEST/DAT as in the above 
example, except that the first byte of EAST/DAT to overwrite the last 
byte of WEST/DAT. 

Error Conditions 

When an APPEND aborts with an error, the destination file involved in 
the APPEND may be left open. Use the RESET library command to 
close the file. 

Sample Uses 

Suppose you have two data files, PAYROLL/A and PAYROLL/B. 

PAYROLL/A PAYROLL/B 

Atkins, W. R. Lewis, G. E. 

Baker, J. B. Miller, L. O. 

Chambers, C. P. Peterson, B. 

Dodson, M. W. Rodriguez, F. 

Kickamon, T. Y. 

You can combine the two files with the command: 


APPEND PAYROLL/B TO PAYROLL/A fENTEff) 

PAYROLL/A now looks like this: 

PAYROLL/A 

Atkins, W. R. 

Baker, J. B. 

Chambers, C. P. 

Dodson, M. W. 

Kickamon, T. Y. 

Lewis, G. E. 

Miller, L. O. 

Peterson, B. 

Rodriguez, F. 

PAYROLUB is unaffected. To see the APPENDed file, type LIST 
PAYROLL/A. 
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ATTRIB 


Assigns protection passwords and attributes to a particular file or a 
group of files. 

You can use ATTRIB to protect a file with passwords. 


ATTRIB filespec (parameters) 


Command 


For filespec ATTRIBs, the parameters are: 

USER = “ password ” sets the user password to password. If this 
parameter is omitted, the user password remains the same. 
If USER = is specified with no password, then any current 
user password is removed. 

OWNER = "password" sets the owner password to password.lf 
this parameter is omitted, the owner password remains the 
same. If OWNER = is specified with no password, then any 
current owner password is removed. 

PROT =level specifies the protection level that is enforced if the 
user password is specified. If this parameter is omitted, the 
level is unchanged. You have to give a file an OWNER 
password before you can set PROT. The optional levels for 
access to a file are: 

EXEC Execute only 

READ Read and execute 

UPDATE Update, read, and execute 

WRITE Write, update, read, and execute 

RENAME Rename, write, update, read, and execute 

REMOVE Remove, rename, write, update, read, and 
execute (allows total access except for 
changing attributes with the ATTRIB 
command. 

FULL Allows total access 

VIS specifies the filespec as visible in the directory 
INV specifies the filespec as invisible in the directory. Use the 
INV parameter to reduce the number of files that TRSDOS 
displays when you issue a DIR command. 


You can abbreviate the levels of PROTection to their first two letters 
except for RENAME and REMOVE, which you can abbreviate to RN 
and RM respectively. 



ATTRIB ['.drive] (disk parameters) 


Command 
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For disk ATTRIBs, the parameters are: 

LOCK protects all visible files not currently protected by setting 
their user and owner passwords to the disk master 
password. 

UNLOCK removes the user and owner passwords from visible 
files if their passwords match the disk master password. 
MPW = “password" states the disk’s current master password. If 
you don’t specify this option, TRSDOS prompts you for it, if 
the password is not PASSWORD. 

NAME[ = "disk name"] specifies the new disk name. If this 
parameter is omitted, the disk name remains the same. 

PW= ["password"] sets the new disk master password to 
password. If this parameter is omitted, the disk master 
password remains the same. 

PW cannot be abbreviated. 

drive defaults to Drive 0. 

Assigning Protection Attributes To a File 

Using the Owner and User Passwords. Passwords are first 
assigned when the file is created. At that time, the owner and user 
passwords are set at the same value (either the password you 
specified, or a blank password if you did not specify one). 

ATTRIB allows you to assign a file two different passwords. The user 
password could be for the operator. It protects a file’s contents at a 
certain protection level (set by PROT). For example, if you want an 
operator to have limited access to a file, you can set the PROTection 
level to READ. Then, using the user password, the operator will be 
able only to read (list) and execute the file, not change, rename, 
re-attrib, or remove it. 

In the same manner, the owner password could be for the 
programmer. Using the owner password, the programmer could 
change, remove, re-attrib, or rename the same file. (When you use 
the owner password to access a file, TRSDOS ignores the 
PROTection level.) 

In short, the user password allows limited access to a file and the 
owner password allows total access. 

Examples 

ATTRIB CUSTFILE/DAT:1 

(USER= *OWNER="BOSSMAN" t PROT = READ ) (ENTER) 

sets the user password blank (so no password is necessary to access 
the file), sets the owner password to BOSSMAN, sets the protection 
level to read and execute only. 
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ATTRIB CUSTFILE/DAT.BOSSMAN 
( USER® 11 SECRET" »PROT = EXEC »INV) (ENTER) 

re-attribs CUSTFILE/DAT. Note that the owner password BOSSMAN 
was required to re-attrib the file. Now, CUSTFILE/DAT has the user 
password SECRET, keeps owner password BOSSMAN, has the 
protection level of execute only, and is invisible in the directory. 

Assigning Protection Attributes To a Disk 

The ATTRIB command also allows you to change the disk name, the 
disk master password, and the password protection of all visible 
filespecs. 

Examples 

ATTRIB (UNLOCK .NAME="MYDISK" ) (ENTER) 

removes all user and owner passwords from the visible filespecs on 
Drive 0 if the filespecs’ current password matches the disk master 
password. It also changes the disk name to MYDISK. Since the 
current master password was not specified with the MPW parameter, 
your computer asks you for it (if it is other than PASSWORD) before it 
executes this command. 

ATTRIB : 1 

< NAME = "DATA" »PW="SECRET" »MPW=“BOSSMAN" ) (ENTER) 

sets the disk name in Drive 1 to DATA, changes the master password 
to SECRET if the current disk master password is BOSSMAN. 

ATTRIB (LOCK) (ENTER) 

prompts you for the disk’s master password (if other than 
PASSWORD) and changes the user and owner passwords of all 
visible, non-password protected files to the disk’s current master 
password. Since no drive was specified, the command is carried out 
on Drive 0. 

ATTRIB : 1 (NAME) (ENTER) 

prompts you for Drive 1 's disk master password (unless it is 
PASSWORD). It then prompts you for the new disk name. 

Sample Uses 

Suppose you have a data file, PAYROLL, and you want an employee 
to use the file in preparing paychecks. You want the employee to be 
able to read the file but not to change it. Then use a command like: 

ATTRIB PAYROLL (I,USER="PAYDAY"» OWNER="BANANA" » 
PROT = READ) (ENTER) 

Now tell the clerk to use the password PAYDAY (which allows read 
only); while only you know the password, BANANA, which grants total 
access to the file. 
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AUTO 


MS *4 D4 

Command 

AUTO [parameters ] [ *][command line ] 



Stores an AUTO command line. This command line automatically 
executes whenever you start up or reset TRSDOS. (That is, after you 
enter the date and time, TRSDOS loads, executes the command line, 
and displays the TRSDOS Ready or BASIC prompt.) 

You can use AUTO to automatically run a program after you type in 
the date. 

command line is limited to 74 characters in length. 

The parameters are: 

■.drive specifies which drive to store the AUTO command line on. 
?\drive displays any AUTO command line stored on drive. 

= -.drive executes any AUTO command line stored on drive. 

In most cases, you can override the AUTO command during start-up 
or reset by (1) holding down the (ENTER) key, or (2) pressing (BREAK) 
while the auto command is executing. 

The exception to this is when you store the AUTO command with the 
* parameter (which disables the (BREAK) key and the ability of the 
(ENTER) key to override AUTO). 

If the AUTO command disables the (BREAK) key and the program is 
non-functional, gaining control of the disk requires several steps. To 
regain control: 

1. Start up the system with another non-AUTOed disk in Drive 0. 

2. When TRSDOS Ready appears, place the non-functional disk in 
Drive 0. 

3. Type AUTO and press (ENTER) , and the runaway AUTO command 
is removed from the disk. 

Use the -.drive parameter to place an AUTO command on a drive 
other than Drive 0. 

Examples 

AUTO BASIC (ENTER) 

loads the BASIC program whenever you start up or reset on Drive 0. 
AUTO (ENTER) 

Turns off the AUTO function currently stored on Drive 0. 

AUTO *D0 IIMIT/JCL; 1 (ENTER) 
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executes the DO file on Drive 1 named INIT/JCL whenever you start 
up or reset. Notice that the * parameter is used. This means the 
operator cannot use (ENTER) to halt the auto command; (BREAK) is also 
disabled. 

AUTO : 1 DEVICE (ENTER) 
places the AUTO command DEVICE on Drive 1. 

AUTO ?: 1 (ENTER) 

displays the AUTO command on Drive 1. 

AUTO = : 1 (ENTER) 

executes the AUTO command on Drive 1. 


Error Conditions 

To place an AUTO command on a disk, it must be write-enabled. 

The system does not check the command line for errors when you 
first enter the AUTO command line. Errors are detected when the 
command is executed. 


Sample Use 

Suppose you want the DEVICE library command to execute 
automatically when you restart your computer. 

Do this by issuing the command: 

AUTO DEVICE (ENTER) 


O 
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BACKUP 




Utility 

BACKUP [partspec}:source drive [TO]\destination drive 

[(parameters)] 


Duplicates (backs up) all or some of the files from source drive to 
destination drive. 

You can use BACKUP to copy the contents of one disk to another. 

Use the parameters to tell the system which group of files to 
duplicate. Use the partspec option to choose a group of files by name 
or extension. (See the Examples.) If no parameters or partspec are 
specified, all visible files are duplicated (unless the diskette types are 
the same, in which case TRSDOS performs a mirror-image backup). 

Note: In most cases, you can see which files a BACKUP command 
would duplicate by issuing a DIR command of source drive using the 
same partspec and parameters as the BACKUP command. 

If you do not specify source drive and destination drive, the system 

prompts you for them. If the source disk has a Master Password other 

than PASSWORD, and you do not state it with the MPW = 

parameter, the system prompts for it as well. ~ 

If the destination drive is not ready, the message 
"Insert DESTINATION disk <ENTER>" is displayed. Insert 
the destination disk and press (ENTER) to continue, or press (BREAK) to 
return to TRSDOS Ready. 

The destination disk must be formatted before the backup 
begins. To format a disk, see the FORMAT command. 

The parameters are: 

MPW = “ password ” specifies the source disk’s Master Password 
SYS backs up system files as well as the visible files 
INV backs up invisible files as well as the visible files 
MOD backs up files that have been modified since the last 
backup 

QUERY = YES questions you about each file before it is backed 
up 

OLD backs up only those files that already exist on the 
destination disk 

NEW backs up only those files that do not already exist on the 
destination disk 

X allows backups with no system disk in Drive 0 
DATE = “M1 ID1IY1-M2ID2IY2" backs up files with modify dates 
between the two specified dates, inclusive. M1/D1/Y1 must 
be before M2/D2/Y2. 

rv 
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= "M1/D1/Y1" backs up files with modify dates equal to the 
specified date 

= “ -M1ID1IY1 ” backs up files with modify dates before or 
equal to the specified date 

= “M1ID1IY1-" backs up files with modify dates after or 
equal to the specified date 

MPW cannot be abbreviated. 

When you specify QUERY = YES, the system questions you for each 
file before it is copied. Answer by pressing: 

m to copy the file. 

(D or (ENTER) to bypass the file and move on to the next one. 

QD to copy the file, turn off the Query function, and 

automatically copy all remaining files. 

After you type the BACKUP command, TRSDOS automatically 
performs one of the three types of backups: “mirror image,” “backup 
by class,” and “backup reconstruct.” The difference between the three 
is of technical interest and is discussed in “General Information.” 

NOTE: A backup by class and backup reconstruct require two disk 
drives. 

For information on backing up “backup limited” diskettes, see 
Appendix M, “Backup Limited Diskettes.” 

Backups With the (X) Parameter 

When you specify the (X) parameter, you do not have to have a 
system disk in Drive 0 when you back up a disk. TRSDOS prompts 
you to insert the proper disks in the proper drive. 

Examples 

BACKUP t: 0 : 1 (SYS >INU) (ENTER) 

examines all files on the disk in Drive 0 and copies all files to Drive 1, 
because all files match the $ partspec. The partspec causes a backup 
by class. 

NOTE: You can use this command to force a backup by class in 
situations where a mirror image would normally be performed. For 
example, it reduces fragmentation of files on the source disk by 
copying them in a more contiguous manner onto a newly formatted 
destination disk. 

BACKUP : 0/ : 1 ( MOD >QUERY = YES >MPW="SECRET") (ENTER) 

copies all visible files from Drive 0 to Drive 1 that have been modified 
(written to) since the last backup. It questions you for each file before 
it is copied, showing the file's mod date and flag. The (MPW=) 
parameter states the Master Password, so the system does not 
prompt you for it. 










BACKUP $/CMD : 0 ; 1 (ENTER) 



copies all visible files with the extension /CMD from Drive 0 to Drive 
1. If the file already exists on Drive 1 it is overwritten. No other files 
on Drive 1 are touched. A backup by class is performed. 

BACKUP /$$S:1 :2 (ENTER) 

backs up all files whose extensions are three characters long and end 
with the letter S. The $ wildcard masks the first two characters of the 
extension, so extensions such as /BAS, /TSS, and /TRS form a 
match. A backup by class is performed. 

BACKUP : 1 :1 (ENTER) 

backs up between two disks in Drive 1. You are prompted to switch 
the source disk and destination disk at the appropriate times. 

The disks used in this type of backup must allow a mirror image 
backup, or the backup aborts. 

This command and the following command could be used to back up 
a data disk. 

BACKUP :0 :1 (X) (ENTER) 

backs up the disk in Drive 0 to the disk in Drive 1. Its main use is to 
back up non-system disks, such as data disks, in a two-drive system. 

When you use this parameter, you are prompted to insert the proper 
disk in Drive 0. You may be prompted to re-insert a system disk into 
Drive 0 during certain backups. 

When the backup is complete, you are prompted to insert a system 
disk back in Drive 0. 

BACKUP - /CMD : 0 ; 1 (ENTER) 

backs up all visible files from Drive 0 to Drive 1, EXCEPT those files 
that have a /CMD extension. A backup by class is performed. 

BACKUP : 1 :2 (NEUI >QUERY = YES) (ENTER) 

backs up only those visible files from Drive 1 that do not already exist 
on Drive 2. You are prompted before each file is moved. 

BACKUP /ASM:3 :2 (DATE="05/06/82-05/10/82" ) 

(INTER) 

backs up all visible files with the extension /ASM, whose modify dates 
fall on or between the specified dates. 

Error Conditions 

The destination disk must be formatted before the backup 
begins. To format a disk, see the FORMAT command. 
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For a backup by class, if the backup is to include system files, the 
destination disk must be newly formatted. BACKUP can’t create a 
system disk if the destination disk contains data files. (Existing files 
may be using certain areas needed by the system.) 

If you are backing up the entire disk, TRSDOS compares the source 
and destination disk Disk ID’s to make sure they are identical. If the 
master passwords or disk names differ, you see the following 
message: 

Destination disk ID is different -- 
NAME=disk name 

DATE -mm/dd/yy 

Are you sure you want to backup to it <Y»N>? 

Press CHD to abort the BACKUP or CD to continue. 

If the disks’ master passwords differ, the following message appears: 

Destination disk ID is different -- NAME=disK 
name 

DATE =mm/dd/yy 

Enter its Master Password or <Break>to abort: 

Press (BREAK) to abort the BACKUP or enter the password to continue. 

If the source and destination disks have a different number of 
cylinders, the following message appears: 

Cylinder counts differ - Attempt mirror-imaSe 
backup ? 

Answer this question with CD to attempt a mirror image backup or 
with CHD to force a backup reconstruct. 

If a mirror image backup is not possible, you get the error: 

Backup aborted* destination not mirror-imaSe 

This appears if the destination disk is missing a cylinder that contains 
information on the source disk. This might be the case if the 
destination disk was formatted with fewer cylinders than the source 
disk, or if cylinders were locked out on the destination disk when it 
was formatted. You can use the FREE library command to check the 
destination disk for locked out cylinders. 

After all the cylinders that contain data are copied to the destination 
disk, BACKUP attempts to remove the modification flags from the files 
on the source disk. If the disk is write protected, the following 
message appears: 

Source disk is write protected? MOD flatfs not 
updated 

Backup by class may NOT be done on a single drive. 
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General Information 


Mirror Image Backup. A mirror image backup is basically a 
cylinder-for-cylinder copy from the source to the destination disk. 

(Only those cylinders that actually contain data are copied.) When the 
backup is complete, the destination disk is an exact copy, or mirror 
image, of the source disk. 

Backup By Class. A backup by class takes place if you specify a 
partspec or any parameter except X or MPW in the command line. 

Backup Reconstruct. A backup by class and a backup reconstruct 
function identically. The only difference is that while you initiate a 
backup by class, the system initiates a backup reconstruct. 

On certain TRSDOS application programs, you can only make a 
limited number of backups. And, when you make a backup on one of 
these programs, the source disk has to be write-enabled during the 
backup or the backup fails. 

Backups With the (X) Parameter. This parameter allows you to back 
up data disks of different sizes or capacities on a two-drive system 
(using backup reconstruct). One-drive system can perform 
mirror-image backups only. When you use the (X) parameter to 
backup non-system disks of different sizes or capacities, system 
modules 2, 3 and 10 must first be put into memory with the SYSTEM 
(SYSRES = number) command. Remember that the (X) parameter is 
used only when there is a non-system disk in Drive 0. 

Mirror Image Backup. TRSDOS makes a mirror image backup if the 
source and destination disks’ size and density are identical, and if you 
specify no partspec or parameters (except X or MPW) in the 
command line. The number of cylinders doesn’t need to be identical 
as long as the destination disk has at least as many cylinders as the 
source disk. 

The date on the destination disk shown with the DIR or FREE library 
commands is changed to the current system date. 

After the backup, the destination disk has its directory on the same 
track as the source disk regardless of where it was before the 
backup. The information on the destination disk is updated to reflect 
its true cylinder count and available free space. 

Backup By Class. This type of backup does a file-for-file copy from 
the source to the destination disk. Files that are fragmented (spread 
over more than one extent) on the source disk are consolidated (if 
possible) on the destination disk. 

Unlike a mirror image backup, files that exist on the destination disk 
but are not on the source disk are not touched in the backup. When 
the backup is complete, the destination disk contains all files moved 
from the source disk plus any other files that existed on the 
destination disk before the backup began. 
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The destination Disk ID is not changed by the backup. 

When the file SYS0/SYS is included in a backup by class, the 
destination disk is configured in the following manner: 

1. The state of the SYSGEN (on or off) is changed to match that of 
the source disk. 

2. The initial date and time prompts (on or off) on power-up are set to 
match those of the source disk. 

3. The default drive configurations match those of the source disk. 

Backup Reconstruct. The system performs a backup reconstruct 
when the size or the density differs between the source and 
destination disks. 

DIR/SYS and BOOT/SYS are not moved to the destination disk in this 
type of backup. 

When a backup by class or a backup reconstruct occurs, only the 
type of files specified will be moved. (This is a departure from the 
Model III hard disk operating system LDOS 5.1.3.) For example, if you 
are moving files to a hard disk with the command BACKUP :5 :2, a 
backup reconstruct is invoked because the two disks are of different 
sizes. This command moves only the visible files. 

If you want all of the files to be moved, then you must use the 
command BACKUP :5 :2 (SYS.INV). This moves visible, invisible, and 
system files to the destination disk. 

Hard disk users should note that system files are stored in specific 
places in the directory. If you use BACKUP to move the visible files 
and then repeat the command with the SYS option, the backup aborts 
if the directory positions required for the system files are already in 
use. If this happens, you can use the PURGE command to delete the 
files that were moved to the disk, and then give the BACKUP 
command with the SYS option. 

Sample Use 

Suppose you have a payroll disk where all of the new employees 
have a file with an extension of /NEW and all of the old employees 
have a file with an extension of /OLD. 

Now suppose you want to have two separate disks: one with old 
employee files and one with new employee files. You could issue the 
command: 

BACKUP /NEW : 0 i 1 (ENTER) 

to move all of the files of new employees from the master disk in 
Drive 0 to another disk in Drive 1. 


W 
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Command 

BOOT [keys \ 


Resets (boots) TRSDOS by returning it to its original start-up 
condition. 

You can use BOOT to return your computer to the TRSDOS copyright 
and startup message. 

The keys are: 

(CLEAR) allows no sysgened configuration to take place. 

(ENTER) allows no breakable AUTO commands to occur. 

□D enters the system debug. No sysgened configuration is 
loaded. 

Note: When you use one of the keys, hold it down until you see 
TRSDOS Ready or the debug display. 

BOOT loads the TRSDOS system in floppy Drive 0 back into the 
computer. It returns the computer back to its normal power-up 
configuration as if the system had been turned off and then turned on 
again. 

Examples 

Remember to hold down the key after you press (ENTER) until you see 
TRSDOS Ready or the debug display. 

BOOT (ENTER) 

resets the system. 

BOOT (ENTER) (CLEAR) 

returns the system to its original start-up condition and ignores any 
sysgened configuration. 

BOOT (ENTER) (ENTER) 

returns the system to its original start-up condition and ignores any 
breakable AUTO commands. 

BOOT (ENTER) (TP 

returns the system to its original start-up condition and enters the 
system debug. No sysgened configuration is loaded, and any 
AUTOed command is not executed. Note: If the AUTOed command is 
unbreakable, QD is ignored. 
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BUILD 




BUILD filespec [(parameters)] 


Command 


Lets you enter data (such as commands) and save it on disk as 
filespec. If you do not specify an extension to filespec, it defaults to 
/JCL. 


You can use BUILD to make a file on a disk. 


The parameters are: 

HEX accepts data in hexadecimal format only. 

APPEND appends the BUILD data to the end of filespec. 

Although you can build any type of data file with this command, it is 
mainly for creating files to be executed with the DO command, 
KSM/FLT, or the PATCH utility. 


The HEX parameter lets you input data in hexadecimal form (see 
Appendix C for a listing of hexadecimal characters). You can use hex 
to generate control characters and graphics symbols which are not 
available from the keyboard. 


The APPEND 
file. 


parameter lets you add data to the end of an existing 


Some programs (such as SCRIPSIT) place their own marker at the 
end of a file. If this marker is in the file, you cannot append BUILD 
data to it unless you: 


• Use the BUILD command to create a new file containing the 
information you wish to append. 

• Use the APPEND library command with the STRIP parameter 
to properly append the new information to the existing file. 


Building a File 

When you enter the BUILD command with a non-existing filespec, 
BUILD creates the file and then allows you to insert lines. 

You can enter a command line of up to 255 character s. JCL files are 
limited to 79 characters per line. To end a line, press (ENTER) . 

To end the file, press (CONTR()L)(SHIFT)(^) at the beginning of a new 
line. The system returns you to TRSDOS Ready. 

Examples 

BUILD DISPLAY; 2 (ENTER) 
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creates a new file named DISPLAY/JCL on Drive 2. TRSDOS allows 
you to insert lines. Type: 




DEVICE (INTER) 

FREE ; 0 (ENTER) 

FREE (ENTER) 

(CONTROLKSHIFTTO 

The first three lines insert the DEVICE, and FREE :0 and FREE 
commands into the “DISPLAY” file. Pressing (C0NTR0L)(SHIFD (W) tells 
TRSDOS that you are finished entering command lines. The system 
returns to TRSDOS Ready. 

Now, whenever you type: 

DO DISPLAY (ENTER) 


TRSDOS executes the file by displaying the device table, the free 
space map of Drive 0, and the free space information for all enabled 
drives. 

BUILD MYKEYS/KSM (ENTER) 


builds MYKEYS on the first available drive. Since the /KSM extension 
was used, a KSM file is built. See the KSM/FLT filter in Appendix I for 
more information. 


BUILD SPECIAL/:0 (ENTER) 


builds SPECIAL on Drive 0. Adding the 7” allows SPECIAL to be 
built without an extension. 


BUILD MY JOBS/JCL (APPEND) (ENTER) 


searches all available drives for MYJOBS/JCL (until it is found) and 
adds the information from this build to the end of the file. If 
MYJOBS/JCL is not found, the file is built on the first available drive. 

BUILD MYPROGA/FIX : 0 (ENTER) 

builds MYPROGA/FIX, which is to be used with PATCH. See the 
PATCH utility for more information. 

BUILD DISPLAY/BLD (HEX) (ENTER) 

builds a file on the first available drive, allowing data to be entered in 
hexadecimal format. Information is entered into this file as 
hexadecimal bytes (with no spaces or other delimiters between them). 


The HEX parameter allows you to enter characters not directly 
available from the keyboard, such as control, printer control, and 
graphics characters. You can enter any one-byte character value. 


A hex build allows 127 hex byte representations (254 characters) per 
logical line. Logical lines may continue on more than one physical line 



1-32 






























as long as a “0D” logical line terminator does not appear. Also, more 
than one logical line can appear on one physical line. 

To create a character string containing graphics characters, type: 

818A90A10D (ENTER) 

This line contains the hexadecimal bytes 81, 8A, 90, and A1. Notice 
that the byte values are packed together. “0D” ends a logical line, 
and (ENTER) ends a physical line. 

If a non-hex digit is entered, the error message “Bad hex digit 
encountered” is displayed and the build aborts. 

Error Conditions 

If the filespec you specify already exists, you will get the error 
message “File already exists” (unless you specify the APPEND 
parameter). 

Sample Use 

Suppose you want to build a file to be used with the PATCH 
command. Issue the command: 

BUILD PRQG/FIX (ENTER) 

and enter the patch lines. 
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COMM 



COMM devspec [(parameters)] 


Utility 


Lets two computers communicate via a device, usually the RS-232 
communications line. 

You can use COMM to let your computer talk with another computer. 
COMM lets your computer: 

• be used as a terminal in communicating with another 
computer. 

• transfer files to and from another computer. 

• spool output from the other computer to your printer. 

Using COMM, you can access: 

• Bulletin Board Systems 

• News and Information Systems 

• Timesharing Systems 

• Electronic Mail Services 

COMM can also communicate with systems that support XON/XOFF 
(Proceed/Pause) protocol. This is a protocol that uses two control 
codes named Device Control 1 and Device Control 3. (The Device 
Control codes are discussed in the (CLEAR) fSHIFT) f*") command 
section.) 

devspec is usually *CL, the RS-232C communications line. 

Note: Before you can use *CL, you have to SET it to its driver 
program COM/DVR. See Appendix L. 

The parameters are: 

XLATES=X’aa£>b’ translates a character being sent. 

XLATER = X’aabb’ translates a character being received. 

XON=X’cc’ changes the XON code. 

XOFF=X’cc’ changes the XOFF code. 

aa is the character to be translated. 
bb is the character aa is translated into. 
cc is the new value of XON or XOFF. 

Enter hexadecimal values in the format X’nnnn’. 

NULL = OFF prevents any nulls (ASCII value 0) from being 

received. 

XLATES and XLATER can be abbreviated to XS and XR. 

XLATES and XLATER let you translate characters that you send to 
and receive from another computer. 
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Example 

Suppose you are using COMM as a terminal to communicate with 
another computer, and you want to print a right bracket (]). It appears 
that you can’t because there is no key on your keyboard that 
produces this character. 

Use the XLATES parameter to produce a (]) by entering another 
character from the keyboard. Type: 

XLATES=X'025D' 

Now when you press (CTRL) fB~) (hexadecimal 02), your computer 
sends the code for a right bracket (hexadecimal 5D) to the other 
computer. Since the Model 4 can display a right bracket when it 
receives a hex 5D, there is no need to use XLATER to translate the 
received character. 

Characters that you receive from another computer can be translated 
to a different symbol using XLATER. Use the same method that we 
used for XLATES. 

See Appendix C for a list of characters and their hex values. 

The Function Keys 

The Function Keys are used to: 

1. Direct the flow of data (text or software) from device to device. 

2. Enable and disable certain functions of COMM, including 
XON/XOFF and full/half duplex operation. 

The Function Keys are divided into two groups: (1) the Application 
keys and (2) the Action keys. 

The Application and Action keys are achieved by holding down all of 
the keys in the sequence, such as (CLEAR)® (hold down (CLEAR) and 
then press ftp . 

The Application Keys 

The Function Keys (CLEAR)fT) through (CLEAR)® designate what 
device an action applies to. 


Function Key 

Device 

Abbreviation 

(CLEAR)fT) 

Keyboard Device 

(*KI) 

(CLEAR)® 

Display Device 

(*DO) 

(CLEAR)® 

Printer Device 

(*PR) 

(CLEAR)® 

Communications Line Device 

(*CL) 

(CLEAR)® 

“Data Send” Device 

(*FS) 

(CLEAR)® 

“Data Receive” Device 

(*FR) 
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Action Keys 

The remaining Function Keys perform an action. Some action keys 
require you to specify an application key ( fCLEAR)fT) through 
(CLEAR) ® ) before you can perform the action. 

(CLEAR) m 


Causes the contents of the "Data Received” (*FR) area in memory to 
be written to disk. This is called "Dump-To-Disk” or DTD. DTD may 
be turned ON before or after a file is received. (You must turn DTD 
ON if a file will exceed the size of the *FR memory area.) 


When you start COMM, DTD is ON. When you perform an *FR 
RESET ( (CLEAR) ® (CLEAR)®) ), DTD is turned OFF. To turn it ON 
again, press (CLEAR)® followed by (CLEAR)fO 


If you are writing data to floppy disks and the RS-232 port is running 
at a speed higher than 300 baud, you have to wait until you receive 
an entire file before turning DTD ON. 


fELEAfi) ® 


Displays the MENU of Function Keys on the display. You can use this 
command any time. 

The display goes from left to right. This is not intended to be a 
complete menu, but a built-in “quick reference” card. 


The screen display is altered to display the menu. Any data you 
receive while the menu is displayed is not lost because COMM saves 
the data in a special area of memory. This data appears on the 
screen after the menu is displayed. 




* * 13 


DUPLX 

ECHO 

ECOLF 

ACCLF REWINDPEOF 

DCC 

CLS 

B-B 

CMD 

HNDSH 

EXIT 

= 1 = 

= 2- 

= 3 = 

ii 

CD 

II 

ll 

in 

ii 

n 

ii 

= 7 = 

= 8 = 

ii 

CD 

ll 

= 0 = 

= : = 

= - = 

*K I 

* 

*D0 

# 

*PR 

*CL *FS *FR 

ft 

DTD 

# 

??? 

ID 

RES 

ON 

OFF 


<£> 

FR-SPEC: HECTOR/HEC:0 MEMORY: 47K 
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1. The devices and functions. (The asterisks above and below the 
function keys indicate that the function is active.) 

2. The amount of available memory. 

3. Asterisks for the shifted function keys. 

4. Asterisks for the unshifted functions keys. 

5. Two asterisks denote a device capable of both input and output. 

6. One asterisk denotes a device capable of either input or output. 

7. If HANDSHAKE is active, the auto XOFF character selected is 
shown in hex. 

8. Displayed filespec of any *FS or *FR filespec. 
fCLEARl dP 

Specifies what file to use when you send or receive data. After you 
specify the file, your computer opens it. If you specify a file that does 
not exist, COMM creates it. 

To specify the name of a receiving file, press (CLEAR)fjD followed by 
(CLEAR)f9~) and answer the following prompt: 

File Name: 

COMM opens the file but does not set aside an area of memory to 
receive the data, so any incoming data is ignored. 

To save incoming data, enter the command (CLEAR) ftD followed by 
(CLEAR) f~Q. Now, data received is placed in the “Data Received” 

(*FR) area of memory, and the data is eventually placed in the file 
you specified. (See (CLEARifT ) for more information on activating 
devices.) 

If a file is already open, the system aborts your (CLEAR)f90 command 
and prints the warning message: 

File Already Open 

This warning prevents you from opening another file before closing 
this one. This protection also applies to files associated with the "Data 
Send” (*FS) area of memory. 

fCLEAff) fO) 

Closes either a receive file or a send file. You must close a receive 
file so its directory can be updated, and so you can receive another 
file. If you reset a device, its buffer is cleared. 

You must turn OFF the *FR or *FS device before you can close the 
associated file. (See (CLEARif^T for information on turning OFF 
devices.) 

(clEBDCD 

Turns ON a device. This is the second command of a two-command 
sequence. 


1-37 
























mm] 




For example, if you want to turn ON the printer, first press (CLEAR) f© 
to indicate that you want to do something with the printer, and then 
press (CLEAR) (T) to indicate that you want to turn it ON. Press 
(CLEAR)® followed by (CLEAR)© to turn the printer OFF. 


(CLEARS 


Turns OFF a device. This is the second command of a two-command 
sequence. 

For example, if you want to turn the printer OFF, first press (CLEAR)© 
to indicate that you want to do something with the printer, and then 
press ©JAR)© to indicate that you want to turn it OFF. Press 
(CLEAR) © followed by (CLEAR) © to turn the printer ON. 

(€LEAR)(gHIFD © 


This is the DUPLEX control, which allows you to select Full-Duplex or 
Half-Duplex. 

Full-Duplex and Half-Duplex indicate how data is sent from one 
computer to another on an RS-232C line. 


Half-Duplex is used with a computer that cannot read data 
while it is sending it or send data while it is receiving it. A 
(CLEAR)(SHIFT)© followed by a (CLEAR)© indicates 
Half-Duplex. 


• Full-Duplex is used with a computer that can read data while it 
is sending it or send data while it is receiving it. A 
(CLEAR)(SHIFT) © followed by a (CLEAR) © indicates 
Full-Duplex operation. 


When you start COMM, it is set to Full-Duplex (Duplex off). 

Some computers and terminals combine Duplex and Echo functions, 
so you should know something about the computer or terminal you 
are communicating with. 

(CLEARlfSHlFD © 


Controls character “Echo”ing. Press (CLEAR)fSHlFT) © followed by 
(CLEAR) © to turn Echo ON. 


You should turn Echo ON if you are communicating with a computer 
or terminal that is operating in full-duplex, but does not display a copy 
of characters it is transmitting to you (called Local Copy). 

Turning Echo ON causes your computer to transmit each character it 
receives back to the computer that sent it. This lets thfe person 
operating the other computer see what is being transmitted. 

Caution: If both ends are set for Echo ON, then the first character 
sent is echoed back and forth indefinitely — or until one end turns 
Echo OFF. 
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[CLEARlfSHlHW 

This command controls Echoing linefeeds. When enabled, any 
carriage return your computer receives causes a linefeed character to 
be transmitted back to the other computer. 

This command is useful since there are a large number of terminals 
and computers that treat a carriage return (ASCII 13) and linefeed 
(ASCII 10) as separate functions. 

When you are communicating with another TRS-80 computer, you 
can turn OFF this function by pressing fCLEAR)(SHIFT) fy) followed by 

(HHBQ. 


(CLEARXSHIFT jCT] 

Controls the ability of your computer to accept a linefeed. COMM 
usually ignores the first linefeed after a carriage return, since most 
computers send both a carriage return and a linefeed. 

In mos t cases, this command is not necessary on TRS-80’s where an 
[ENTER) is treated as both a carriage return and linefeed. 

(ELEAR)(gHim r%] 


Positions to the start of an *FR or *FS file, so you can start again. 

For example, if you are receiving a file and it aborts with an error, you 
can startover by pressing (CLEARO n followed by fCLEAR](SHIFT)f%\ 
Then you can attempt to receive the file again. 


MM 


WH .)® 


Appends new data to the end of a file. This command applies to the 
“Data Received” (*FR) area of memory only. If you open an existing 
file and then press (CLEAR) dP) followed by [CLEAR)($HlFf) (D. you can 
append new data to the end of the file. 


[CLEAR] 




<D 


Displays control characters that are being received or sent. You can 
use this command to detect if you are receiving unwanted control 
characters. If you are receiving unwanted control characters, you can 
use the XLATER to translate them. 


[CLEAR] [SHIFT] rp 

Erases the contents of the screen and places the cursor in the upper 
left corner. No data is transmitted. 


[CLEAR] [SHIFT) fT] 

When followed by an ON command RCLEARFp ), your computer uses 
all 8 bits of a character it receives. Normally, bit 8 is either not 
present or invalid, so COMM removes it from each character it 
receives. 
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Do not turn this option ON unless the RS-232C word length is set to 
8. You can use the SETCOM library command to set the word length 
before you enter COMM. 

(CLEARlfSHIFD rOl 

Allows you to enter a TRSDOS library command from COMM. 

For example, when you type: 

DEVICE (ENTER) 

the device table is displayed on your screen. The message 
“Command complete” is displayed below the device table. 

NOTE: If the specified library command attempts to change HIGH$, 
the command aborts and TRSDOS returns you to COMM. 

(5LEAB)(5HIFT) r*l 

This command controls the handshaking on the data line. 

Handshaking is the agreed-upon method that two communicating 
computers use to control the flow of data between them. If this option 
is turned ON, COMM responds to the following codes when your 
computer receives them from the communications line: 


Symbol 


Value 

Description 

DC1 

17 

X’11’ 

— Resume transmission (XON or 
Proceed character) 

DC2 

18 

X’12’ 

— Turns the *FR device ON 

DC3 

19 

X’13’ 

— Pause transmission (XOFF or 
Pause character) 

DC4 

20 

X’14’ 

— Turns the *FR device OFF 

NOTE: You 

can use the XON and XOFF parameters to change the 


codes to other values when entering COMM. 

The above codes are part of the ASCII standard. DC1 and DC3 
control the device that is transmitting data. They tell it when to start 
and stop transmitting. 

DC2 and DC4 control the recording device. They tell it when to start 
and stop recording. These codes use the “Received Data” device 
(*FR) to accumulate the received data. If you use DC2 and DC4, be 
sure you have created an *FR file with (CLEAR) ® and (CLEAR)®. 

When a DC3 is received, it suspends transmission through the *CL 
device until a DC1 is received. Any characters that are received are 
accepted, but none are transmitted. You can override a received DC3 
with the *CL ON command ( (CLEAR)® (CLEAR) ®). 
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Handshaking can also be activated when a given character is 
transmitted. Do this by pressing (CLEARXSHIFDf*! followed by the 
character you want to pause on. 

Typically, the (ENTER) key is specified so that line-at-a-time 
transmission occurs with automatic pausing at the end of each line. 

When handshaking is ON, COMM pauses transmission whenever the 
specified character is transmitted until it (1) receives a DC1 from the 
other system, or (2) receives a *CL ON command from the keyboard. 

(CLEAR)(SHIFT) r=~) 

Exits to TRSDOS Ready. It does not require any ON or OFF code. 

Before COMM stops running, it checks the “Data Received” device 
(*FR) to see if any open files exist. If there is an open file, COMM 
closes it before it exits to TRSDOS. This feature prevents you from 
having unclosed files in your system. 

Quick Reference Label 

If you are a beginning COMM user, you may find it helpful to make a 
label containing each key’s function and place the labels directly 
above the keyboard. Label the keys as follows: 


Key 

Unshifted 

SHIFTed 

1 

*KI 

Duplex 

2 

*DO 

Echo 

3 

*PR 

Echo-Linefeed 

4 

*CL 

Accept-Linefeed 

5 

*FS 

Rewind File 

6 

*FR 

Position @ EOF 

7 

DTD 

DCC 

8 

Menu 

Clear Screen 

9 

ID 

8-bit mode 

0 

Reset 

Command 

; 

On 

Handshaking 

- 

Off 

Exit 


Logging-On to CompuServe 

You can use your Model 4 and COMM to log-on to CompuServe. To 
log on to CompuServe, you must first buy a Universal Sign-Up Kit 
(Radio Shack Cat. No. 26-2224). Next, follow these steps: 

1. First, use the SET command to SET *CL to COM/DVR (see 
Appendix L). Then issue the command: 

SETCOM (W0RD = 8 » PAR ITY = 0FF »STOP= 1 ) (ENTER) 

2. Type: 

COMM *CL (ENTER) 
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3. Now you need to dial CompuServe’s number that comes in the 
Universal Sign-Up Kit. Depending on which modem you are using, 
you either dial the number on a phone or you must enter the 
commands that cause the modem you are connected to dials the 
number for you. See your modem manual for the correct 
procedure. 

4. After the number is dialed, wait for a “carrier tone” that 
CompuServe sends to tell you that you are connected. 

5. Now press (CONTROUfiT) to send a hexadecimal value of 03 to 
CompuServe. 

6. CompuServe prompts you on your video display with: 

User ID: 

Password: 

Answer each prompt with the numbers supplied in the Universal 
Sign-Up Kit and fEWTER) . 

7. You are now logged-on to CompuServe. 

COMMunicating with Bulletin Board Systems 

A Bulletin Board System (BBS) is typically a small computer used by 
individuals, schools, or companies that provides a communication link 
between its users. 

With some TRS-80 Bulletin Board Systems, you can receive graphics 
characters. For you to be able to accept these graphics, the 
COM/DVR driver has to be initialized at 8 bits per word (see the 
SETCOM library command) and you have to use 8-bit mode in 
COMM f (CLEAR)fSHlFD m followed by (0JAg)CD). 

COMMunicating with Other Computers 

This section shows you how to use COMM to communicate with other 
computers. The first example describes how a TRS-80 communicates 
with a mainframe computer. The second example describes how two 
TRS-80’s can communicate. 

COMMunicating with a Mainframe 

When a TRS-80 communicates with a mainframe computer, in most 
cases it is not necessary to change the default device or function 
settings when you enter COMM. Most mainframes operate as the 
host computer while you operate as a terminal, and the mainframe 
provides echo functions for you. You must be sure to specify the 
RS-232C parameters when setting up the COM/DVR driver to match 
those expected by the mainframe. 

To transfer a file from a mainframe to your TRS-80 computer, use the 
following procedure: 














1. Type in the command which causes the mainframe to list the file, 
but do not press (ENTER) . 

2. Specify your receive file by pressing (CLEAR) (1T) followed by 
(CLEAR)f5T Type in the filename in response to the prompt. 

3. Press (CLEAR) flP followed by (CLEAR) fn to open the receive area of 
memory. If the file you wish to receive is larger than your available 
area of memory, you should then press (CLEAR) CT) followed by 
(CLEARl fTl. This causes the file to be written to the disk as it is 
being received. 

4. Press (ENTER) to start the file listing. 

5. When the listing is complete, press (CLEAR) f6l followed by 
(CDDffiGE). to turn OFF the *FR and if you have not already done 
so, press (CTEARX T) followed by (CLEAR) fD to write the file to disk. 

6. When the disk write is complete, type (CLEARJ CtD followed by 
(CLEAR) fCT) to turn off DTD and to close the receive file. 

To transfer a file from your TRS-80 computer to a mainframe, use the 

following procedure: 

1. Designate the file that you want to send by pressing (CLEAR) C5) 
followed by (CLEAR)flT) and entering the name of the file in 
response to the prompt. 

2. Turn on the handshake mode by pressing (CLEARXSHIFT)f*') 
followed by (ENTER) (assuming that the line terminating character in 
your file is (ENTER) ). 

If the mainframe does not support handshaking, first try to transfer 
the file withouTtheTtandshake mode. If this doesn’t work, contact 
the mainframe’s computer site and find out how to send files to 
that mainframe. 

3. Open the file at the host end and ready it for receiving information 
by whatever command process your host requires. 

4. Turn on your file send by pressing (CLEAR)(1P) followed by 
(CUIABGD. 

Note that one line of your file is transmitted and then your machine 
pauses. Once the host sends you the XON, the next line of the file 
is automatically transmitted. 

If you are operating in half-duplex, you may see the entire file 
displayed without any pauses. The file is being read from your disk 
and put in an area of memory where it waits to be transmitted. 

5. When the transmission is complete, turn off the handshake mode 
by pressing (5LEAR)(SHIFD m followed by (CLEAR) f 3 ! 
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6. Close the file at the host end by whatever command process the 
host accepts. You may then close your file send by pressing 
(CLEAR)fiP ) followed by (CLEAR)dP ) (which turns off the *FS and 
closes the file). 

If you want to force the transmission to resume after a line is 
ended, you may turn the *CL back on by pressing (CLEAR1 C41 
followed by (fcLEAR) Hl. 

COMMunicating Between Two TRS-80's 

When you use COMM to communicate between two TRS-80’s, one 
end has to run on half-duplex f (CLEAR)(SHIFT) CD followed by 
(CLEART T)) and echo f (CLEAR)(SHIFD f^l followed by (RLEARi mt. If files 
are to be sent and received, the RECEIVING end should run 
half-duplex and echo. 

To transfer files between two TRS-80’s, use one of the following two 
methods. Use Method A if you are operating above 300 baud. Use 
Method B if you are operating at 300 baud. 

Method A 

1. The sending end presses (CLEAR)f5~) followed by (CLEAR)f9~) and 
enters the name of the file to be sent. 

2. The receiving end presses (CLEAR) f6) followed by (CLEAR)fF) and 
enters in the name of the file to be received. Turn the dump-to-disk 
(DTD) OFF by pressing (CLEAR) (T) followed by (CLEAR) f 71 ). This 
stores the file in memory as it is received. 

If the sending end supports XON/XOFF handshaking, then you 
should turn HANDSHAKE ON by pressing (CLEARlfSHlFD r*! 
followed by (ELEARl fD. 

3. When both ends are ready, the receiving end presses (CLEAR) Ctp 
followed by (CLEARlfH , after which the sending end presses 
(CLEAR) (TT) followed by (CLEAR) fT). 

If your free area of memory decreases to less than 2K during 
receipt of the file, a warning message is issued and an XOFF is 
automatically sent to the sending end. 

Transmission from the sender should cease. Once it does, dump 
the receive area of memory to disk by turning on DTD by pressing 
(CLEAR) (T) followed by (CLEAR) fT). 

You can observe the increase in available memory space by 
displaying a menu as the area of memory is written to disk. Once 
ample space is available, turn off the DTD by pressing (CLEAR) fT) 
followed by (CLEAR) ! " 17 ) . 


You can then manually restart the sender’s file by transmitting an 
XON from your keyboard with (C0NTR0L) (D. 
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4. The receiving end presses (CLEAR)© followed by (CLEAR)© when 
it has received all of the file. The last receive area of memory 
should be dumped to disk by turning on DTD ( (CLEAR)© followed 
by (SUM)©). 

The sending end presses (CLEAR)© followed by (CLEAR) © and 
then (CLEAR) © followed by (CLEAR)®. 

5. When the receiving end has finished writing the information to the 
disk, close the file by resetting the *FR ( (CLEAR)© followed by a 
(CLEAR) ©). This performs an *FR OFF and a DTD OFF, and it 
closes the file just received. 

Method B 


1. The sending end presses ( (CLEAR) © followed by ( (CLEAR) © and 
enters in the name of the file to be sent. 


The receiving end presses ( (CLEAR)© followed by ( (CLEAR)© and 
enters in the name of the file to be received. 


The dump-to-disk (DTD) must be turned ON by pressing (CLEAR) © 
followed by (CLEAR) ©. Check to see if it is already ON by 
displaying a menu ( (CLEAR)© ) and noting if an asterisk is 
displayed beneath its key. 


3. When both ends are ready, the receiving end presses (CLEAR) © 
followed by (CLEAR)© . The sending end then presses (CLEAR)© 
followed by (CLEAR) © to turn ON the receive and send files. 

4. When the receiving end has received all of the file and it is written 
to the disk, close the file by resetting the *FR. Press (CLEAR) © 
followed by (CLEAR)© . This performs an FR OFF and a DTD OFF, 
and it closes the file just received. The sending end then presses 
(Clear) © followed by (Clear) ©. 




Technical Information 

This section describes some of the more technical aspects of COMM 
operation. This information allows you to predict how COMM will 
perform during higher speed I/O operations. 

Main memory usage 

COMM uses all available memory below the top of memory mark 
(HIGHS) for dynamic buffering of device I/O. You can see or set this 
value with the MEMORY command. 

The amount of buffer space devoted to each logical device 
dynamically expands and shrinks according to how quickly data is 
sent to a device and how fast the device can process the data it 
receives. Each buffer is essentially a variable length First-In, First-Out 
(FIFO) storage compartment. 
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The amount of free space available for the buffers is noted in the 
bottom line of the menu display. When this free space shrinks to less 
than 2K (2048 characters), a warning message is displayed and an 
XOFF is automatically sent to the communications line (*CL). 

This function is useful when you are receiving a file from a system 
that supports handshaking. (The (CLEAR)(SHIFT)f*~) command 
describes the supported handshaking.) 


Break commands 


COMM generates a modem break (long space) when you press the 
(BREAK) key. A modem break is used on many mainframe systems to 
indicate you want to abort a function that is occurring at the other 
computer. 

However, for small computers, detecting a modem break is more 
difficult, so you have to select a control character to be treated as a 
“break” command. 


To transmit a break character to another computer, press (CONTRODflT) 
if the other computer is a Model II, 12 or 16. Press (CONTROL) fAl if the 
other computer is a Model I or III. 


Escape code sequences 

Some systems transmit control codes to indicate that a cursor 
movement or action is to be performed. Many systems have adapted 
a two-character sequence, which does not perform the intended 
function in COMM. 

If you are working with one of these systems, you should contact the 
operators of the other system and ask if there is a way to prevent 
these control sequences from being sent to your system. 

Some systems support several different types of terminals and 
computers, so with a little experimenting, you should be able to find a 
terminal setting that suits your needs. 



Receiving large files from another system 

If you receive files that won’t fit into memory in one piece, you may 
have to use handshaking to reduce the possibility of losing data. 


r\ 
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CONV (CONV/CMD) 


Utility 

CONV [partspec]:source drive [:destination drive [(parameters)] 


Allows you to move (convert) data files from a TRSDOS 1.3 (Model 
III) diskette onto a TRSDOS Version 6 formatted diskette. 

Use this command with data or BASIC ASCII files. TRSDOS 1.3 
application programs will not work on TRSDOS Version 6. To use 
TRSDOS 1.3 programs on the Model 4, start up your system with a 
TRSDOS 1.3 system diskette in Drive 0. 

The parameters are: 

VIS moves visible files 
INV moves invisible files 
SYS moves system files 

NEW moves only those files that do not already exist on the 
destination disk. 

OLD moves only those files that already exist on the destination 
disk. 

QUERY = NO specifies that you are not to be questioned before 
each file is moved to the destination disk. 

DIR displays a short directory of a TRSDOS 1.3 disk. If you do 
not specify destination drive, a short directory is displayed. 

If you specify DIR, no files are moved. 

If you don’t specify VIS, INV, or SYS, TRSDOS moves all three types 
of files. 

The TRSDOS 1.3 disk must be a non-limited backup disk. Some 
programs such as SCRIPSIT and VISICALC are limited backup disks. 

If you have data files on a TRSDOS 1.3 limited backup disk, you must 
COPY these files (under TRSDOS 1.3) to a non-limited backup disk 
before you can CONVert them. 

The source drive cannot be Drive 0. 

When you specify a partspec , only those files matching the partspec 
are moved to the destination disk. 

When you do not specify the QUERY = NO parameter, you are 
questioned before each file is moved. Answer the prompt by pressing: 

(X) to copy to file. 

QD or (ENTER) to bypass the file and show the next one. 

Caution: Do Not move BASIC/CMD or any other existing TRSDOS 
system files. 
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Examples 

CONU : 2 : 1 (ENTER) 

moves all files from Drive 2 onto Drive 1. You are questioned before 
each file is moved. If the file already exists in Drive 1, you are asked 
again before it is copied. 

CONV : 1 :0 (VIS ,Q=N0) (ENTER) 

moves all visible files from Drive 1 onto Drive 0. You are not 
questioned before each file is moved. 

C0N0 :2 :0 (NEW) (ENTER) 

moves only those files from Drive 2 that do not already exist on 
Drive 0. 

C0N0 $$$DAT A : 1 :2 (OLD) (ENTER) 

moves any file whose filename is seven or eight characters long, the 
4th through 7th characters are DATA, and that already exists on Drive 
2. You are questioned before each file is moved. 

CONV : 1 (DIR) (ENTER) 

displays the directory of the TRSDOS 1.3 disk in Drive 1. 

CONV : 1 (INU >DIR ) (ENTER) 

displays the invisible files of the TRSDOS 1.3 disk in Drive 1. 
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COPY 





Command 

COPY source [TO] destination [(parameters)] 


Copies the source to the destination. 

Source and destination can be a filespec or a devspec. Destination 
can also be a drive number. 

The parameters are: 

LRL=nnn specifies the logical record length (1 to 256) for 
destination. If omitted, destination will have the same LRL 
as source. 

CLONE = NO specifies that destination is not to have the 
attributes of source. 

ECHO causes any character copied from a devspec to be printed 
on the screen. 

X allows a single drive copy. 

The LRL parameter lets you restructure files to make them compatible 
with other programs. It is also useful when converting a source file 
from one format to another. 

If you wish to append two files with different LRLs, this parameter can 
be used to make the LRLs match. If LRL is not specified, it defaults to 
the LRL of source. 

If CLONE is not specified, the directory entry as well as the contents 
of source copies to destination. The owner and user passwords are 
copied, along with the assigned protection level, the visibility in the 
directory, the create flag, the last written-to date, and the modified 
status of the file. 

If CLONE = NO is specified, the system date becomes the last 
written-to date for the destination file. If an existing destination file 
was copied over, the attributes of the destination file (except for the 
date) are unchanged. If the COPY command creates a new file, any 
password included becomes both the user and owner password of the 
destination file and the file’s Mod Flag is set. The destination file is 
visible, even if the source file was invisible. See the ATTRIB library 
command for more information on file attributes. 

Examples 

COPY TEST/DAT TO ; 1 (ENTER) 

searches the disk drives to find TEST/DAT and copies it to Drive 1. 

COPY TEST/DAT, PASSWORD:® TO : 1 (ENTER) 
copies the protected file TEST/DAT. PASSWORD from Drive 0 to 
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Drive 1. All parts of the destination file, including the password, are 
the same as those of the source file. 



COPY TEST/DAT : 0 TO MYFILEs 1 (ENTER) 

copies TEST/DAT on Drive 0 to MYFILE/DAT on Drive 1. Since the 
destination filespec does not contain an extension, it defaults to /DAT 
to match the source. 

COPY DATA/NEW : 0 TO /OLD : 0 (HUE) 

copies DATA/NEW on Drive 0 to DATA/OLD on Drive 0. Since the 
destination filespec does not contain a filename, it defaults to DATA 
to match the source. 


COPY TEST/DAT:0 TO TEST/DAT.CLOSED : 1 
(CL0NE = N0 ) (ENTER) 

copies TEST/DAT from Drive 0 to Drive 1 and assigns the user and 
owner passwords CLOSED. To assign a password to a destination 
filespec, the CLONE parameter must be turned off. 

COPY DATA/U5B:0 TO DATA/U28:1 <LRL=128) (ENTER) 

copies DATA/V56 on Drive 0 to DATA/V28 on Drive 1. The LRL of 
DATA/V28 is set to 128. 

COPY *KI TO *PR (ECHO) (ENTER) 


copies from the keyboard to the printer. As keys are pressed, they are 
sent to the line printer. The keystrokes are visible on the video 
because the ECHO parameter is specified. Pressing 
) (SHIFT) ((«D or (BREAK) terminates the copy. 


(MU 


When copying from devspec to devspec, it is very important that all 
devices specified be assigned and active in the system. Any routing 
or setting affecting the devices may affect the copy. 


It is very important to be aware that you can generate non-ending 
loops that lock up the system when copying between devices. Be 
sure to have a good understanding of this type of copy before you 
use it. 


COPY *K I TO KEYIN/NDkl ; 0 (ENTER) 

sends the keystrokes entered from the keyboard to the file 
KEYIN/NOW on Drive 0. If the file already exists, it is written over. To 
view the characters as you type them, use the ECHO parameter. 
Pressing (C0NTR0L)(SHIFT)(^ ) terminates the copy. 


COPY TEST/DAT .SECRET : 0 (X) (ENTER) 


copies TEST/DAT.SECRET from one disk to another. 

The destination file TEST/DAT.SECRET is visible, and its owner and 
user passwords are set to SECRET. 
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When you use the (X) parameter, a TRSDOS system disk is not 
required in the copy if the proper system modules (1, 2, 3, and 4) are 
loaded into memory (see the SYSTEM (SYSRES) library command). 

During the copy, the following disk swap prompts are repeated until 
the copy is complete. The prompts are: 

Insert SOURCE dish (ENTER) 

— Contains the file to be copied. 

Insert SYSTEM disK (ENTER) 

— Any TRSDOS SYSTEM disk. If system modules 1, 2, 3, and 4 are 
loaded into memory, press (ENTER) at this prompt. 

Insert DESTINATION disk (ENTER) 

— Receives the file being copied. May appear twice in a row. The 
disk must have a different Disk ID (disk name, master password, or 
date) from the source diskette. (If it is a system disk, use ATTRIB if 
you need to change its Disk ID.) 

You cannot use the (X) parameter in copies involving logical devices. 

Sample Use 

Whenever a file is updated, use COPY to make a backup file on 
another disk. You can also use COPY to restructure a file for faster 
access. Be sure the destination disk is already less segmented than 
the source disk; otherwise the new file could be more fragmented 
than the old one. (See FREE for information on file fragmentation.) 

To RENAME a file on the same disk, use RENAME, not COPY. 












CREATE 



Advanced Programmer’s Command 
CREATE filespec (parameters ) 


Creates a file named filespec and pre-allocates space for its future 
contents. 

You can use CREATE to prepare a file which will contain a known 
amount of data. This usually speeds up file write operations. File 
reading is also faster, since pre-allocated files are less segmented or 
dispersed on the disk — requiring less motion of the read/write 
mechanism to locate the records. 

When a file is CREATEd, TRSDOS does not recover unused space at 
the end of the file (each time you finish using it). If you exceed the 
created size, TRSDOS allocates extra space for your file as you write 
to it. 

The parameters are: 

LRL =number assigns number as the record length of filespec. 
number can be from 1 to 256. If you omit this parameter, 
the record length defaults to 256. 

REC =number assigns the specified number of fixed-length 
records to the file. 

SIZE = number allocates disk space to the file as number (in K). 

You have to specify (1) SIZE or (2) LRL and REC. 

(For more information about record lengths and types, see “Disk 
Files” in the Technical Reference Manual.) 

CREATE also lets you permanently assign additional space to a file 
that already exists. Use the appropriate parameters for the new file 
size. 

Examples 

CREATE NEWFILE/DAT:0 <LRl=128»REC=100) (ENTER) 

creates a file named NEWFILE/DAT on Drive 0 and allocates space 
for one hundred 128-byte records. 

CREATE GOOD/DAT <REC = 50) (ENTER) 

creates a file named GOOD/DAT on the first available drive and 
allocates space for fifty 256-byte records. 

CREATE INVENT/DAT (SIZE = 20) (ENTER) 

takes the already existing file named INVENT/DAT and increases its 
size to 20K. 
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Error Conditions 



If the specified SIZE (or LRL times REC) would cause an existing file 
to become smaller than it presently is, the error message “File exists 
larger” appears. 

Sample Use 

Suppose you are going to store personnel information on no more 
than 250 employees, and each data record will look like this: 

Name (Up to 25 letters) 

Social Security Number (11 characters) 

Job Description (Up to 92 characters) 

Your records would need to be 25 + 11 + 92 = 128 bytes long. 

You could create an appropriate file with this command: 

CREATE PERSONNL/TXT ( REC = 250 >LRL= 128 ) (ENTER) 

Once created, this pre-allocated file would allow faster writing than 
would a dynamically allocated file, since TRSDOS would not have to 
stop writing periodically to allocate more space (unless you exceed 
the pre-allocated amount by adding more than 250 employees). 
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Command 

DATE [mm/ddlyy] 


Resets the date or displays the current system date. 

You can use DATE to see today’s date. You can also use DATE to 
change the date that TRSDOS uses. 

You first set the date when you start up your computer. DATE lets 
you change it without turning your computer off and on. 

Use mmldd/yy to reset the date, mm is a 2-digit month specification; 
dd is a 2-digit day of the month specification; yy is a 2-digit year 
specification. If you omit mmlddlyy, TRSDOS displays the current 
date. 

It is important to set the date because TRSDOS uses the date when 
creating and accessing files, making backups, and formatting disks. 

TRSDOS restricts the date to between 01/01/80 and 12/31/87. If you 
enter a date outside of this range, an “Illegal date” error results. 

Examples 

DATE (ENTER) 

displays the current date, such as: 

Fri i Oct B » 19B2 
for Friday, October 8, 1982. 

DATE 10/09/82 (ENTER) 

resets the date to October 9, 1982 and displays the new date. 
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DEBUG 



Advanced Programmer’s Command 
DEBUG [(switch)] [(parameter)] 




The DEBUG command sets up the debug monitor, which allows you 
to enter, test, and debug machine-language programs. 

The switches are: 

ON turns on DEBUG 

OFF turns off DEBUG 

The parameter is: 

EXT turns on the extended debugger 

EXT, ON, and OFF can be abbreviated to E, Y, and N. 

Once you have turned on DEBUG, you automatically enter the debug 
monitor whenever you do one of the following: 

1 . Press the (BREAK) key (provided (BREAK) is enabled) 

2. Load and execute a user program (as long as the file’s 
protection is not execute only) 

You can also automatically activate the debugger by holding down the 
QD key while the system is booting. 

While in the DEBUG monitor, you can enter any of a special set of 
single-key commands to study how your program is working (as 
detailed under Command Description below). 

EXT loads a separate block of the system debugger into high 
memory. While DEBUG is on, TRSDOS automatically protects this 
area of memory from being overlaid by BASIC or other user 
programs. 

If you execute a program with execute only protection, DEBUG turns 
off. 

Examples 

DEBUG (ENTER) 

turns on the standard DEBUG and waits for it to be activated. 

DEBUG (EXT) (ENTER) 

turns on extended DEBUG (loads it into high memory) and waits for it 
to be activated. 

DEBUG (OFF) (ENTER) 
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turns off standard or extended DEBUG. 


DEBUG (OFF >EXT) (ENTER] 

Turns off DEBUG and attempts to reclaim the high memory occupied 
by the extended debugger. (If anything is loaded in high memory 
below the extended debugger, this area is not reclaimed.) 

To enter the monitor when DEBUG is on, type: 

filespec (ESTER) 

TRSDOS loads the program (as long as the file’s protection level is 
not execute only) and transfers control to DEBUG. (You can also 
enter the monitor by pressing (BREAK) .) 

Following is a sample display of the debugger screen. 
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The debug display contains information about the Z-80 
microprocessor registers. The display is set up in the following 
manner: 

The register pairs are shown along the left side of the display, 
from top to bottom. The current contents of each register pair are 
shown immediately to the right of the register labels. 

The AF and AF’ pairs are followed by the current status of the 
flag registers to the right of the register contents. The other 
register pairs are followed by the contents of the 16 bytes of 
memory they are pointing to. The contents are shown in both 
hexadecimal and ASCII representations. Non-displayable ASCII 
characters are represented by periods. 

The PC register shows the memory address of the next 
instruction to be executed. The display to the right of that 
address shows the contents of that address and the next 15 
addresses. 
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The bottom four lines of the screen show the contents of the 
memory locations indicated by the address at the left of each 
line. These locations vary depending upon which command is 
used. 

Command Descriptions 

When the DEBUG monitor is displayed, you can enter one of the 
following single-key commands. 

Any value entered as an address or a quantity must be entered as a 
hexadecimal number. 

To cancel an incorrect command, press CXD. 

A (ASCII Modify) 

A address 

Enter the above command line to modify address. If address is 
displayed in the monitor, vertical bars appear around it. 

After you enter address, it and the current byte appear in the lower 
left corner of the screen. To modify the byte, type the new ASCII 
value and press: 

• (SPACE BAR) to modify the byte and move to the next address. 

• (ENTER) to modify the byte and exit from the A command. 

If you do not specify address, TRSDOS uses the current “memory 
modification address” (shown by the vertical bars). 

Example: 

AD004 (SPACE BAR) 

causes address D004 and the current byte value to appear in the 
lower left corner of the screen. TRSDOS allows you to enter the new 
byte value. Then press (SPACE BAR) to continue, or (ENTER) to end. 

B (Move Block of Memory) 

B starting address,destination address,number of bytes 

Enter the above command line to move a block of memory from 
starting address to destination address. 

Always specify a non-zero number of bytes. If you enter number of 
bytes as 0, TRSDOS moves a block of 65,535 bytes to destination 
address, causing the extended debugger to function improperly. 

Example: 

B3E04 *4E34 * 14E (ENTER) 

moves the 14E-byte block of memory from 3E04 to 4E34. 
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C (Call Instruction) 

Press CD to single-step through the instructions pointed to by the PC 
register. If a call instruction is encountered, the routine that it calls 
is executed. 

D (Display) 

D address 

Enter the above command line to display memory beginning at 
address. 

Example: 


usm 


displays memory beginning at address E404. 

F (Fill Memory) 

F first address, last address, byte 

Enter the above command line to fill the block of memory from first 
address to last address with the value byte. 

Example: 

F3D08 ,3E14 *00 (ENTER) 

fills the block of memory from 3D08 to 3E14 with the value 00. 

G (Go to an Address and Execute) 

G address, breakpoint 1, breakpoint2 

Enter the above command line to begin execution at address. If 
address is omitted, execution begins at the PC address. 

breakpointl and breakpoint2 are optional breakpoint addresses where 
execution stops. The breakpoints must be in memory. The system 
removes them when you return to debug. 

Example: 

GE0FF *F001 *F201 (ENTER) 

begins execution at E0FF. Stops execution at breakpoint addresses 
F001 and F201. 

H (Hex Modify) 

H address 

Enter the above command line to modify address. If address is 
displayed in the monitor, vertical bars appear around it. 
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After you enter address, it and the current byte appear in the lower 
left corner of the screen. To modify the byte, type the new 
hexadecimal value and press: 

• (SPACE BAR) to modify the byte and move to the next address. 

• (ENTER) to modify the byte and exit from the H command. 

• QD to exit from the H command without modifying the byte. 

If you do not specify address, TRSDOS uses the current “memory 
modification address” (shown by the vertical bars). 

Example: 

HD004 (SPACE BAR) 

causes address D004 and the current byte value to appear in the 
lower left corner of the screen. TRSDOS allows you to enter the new 
byte value. Then press (SPACE BAR) . (ENTER) , or (T) to continue. 

I (Single-Step Execution) 

Press CD to single-step through the instructions pointed to by the PC 
register. This command is identical to the C command except that any 
calls encountered are stepped through instruction by instruction. (Note 
that RST 28H, RST 30H, and RST 38H instructions automatically 
convert the I command to a C command.) 

J (Jump) 

Press QD to increment the program counter (PC) by 1. 

O (Return to TRSDOS Ready) 

Press CD to return to TRSDOS. DEBUG is not turned off. (Use the 
DEBUG (OFF) command to turn DEBUG off.) 

Q (Port) 

There are two kinds of ports — input and output. You read an input 
port and you write to an output port. 

Q port 

Enter the above command line to read the byte at port and display its 
value. There are 256 input ports (00 - FF). 

Example: 

045 (Enter) 

displays the value of port 45 in the lower left corner of the screen. 
Qport,byte 

Enter the above command line to write the value of byte to port. 

There are 256 output ports. 
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Example: 

045 >04 

writes the byte value of 04 to port 45. 

R (Register Pair) 

R register pair code contents 

Enter the above command line to change the specified register pair’s 
contents to the new contents. There must be a space between 
register pair code and contents. 


The register pair codes are: 


AF 

for 

AF 

AF 

for 

AF 

BC 

for 

BC 

BC’ 

for 

BC’ 

HL 

for 

HL 

HL’ 

for 

HL’ 

DE 

for 

DE 

DE’ 

for 

DE’ 

IX 

for 

IX 




IY 

for 

IY 




SP 

for 

SP 





Example: 

RBC 3D01 

changes the contents of register pair BC to the value 3D01. 

S (Full Screen Mode) 

Press ® to change the monitor format from the register display 
mode to full screen mode. The full screen mode displays a page of 
memory (256 bytes) beginning with the current display address (see 
the D command). 

U (Update) 

Press QD to constantly update the display and to show any active 
background tasks. To cancel this command, hold down any key for 
several seconds. 

X (Return) 

Press (3D to return the display to the normal register display mode. 

; (Advance Memory) 

Press CD to advance the memory display 64 bytes in the register 
mode and 256 bytes in the full screen mode. 

- (Decrement Memory) 

Press GD to decrement the memory display by 64 bytes in the 
register mode and 256 bytes in the full screen mode. 
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Disk Read/Write Utility 

Lets you read or write to a specified block of memory. The command 
line is: 

disk drive,cylinder,starting sector,operation,address,number of 
sectors 

address is the starting address in memory where the information read 
from the disk is to be placed, or where information written to the disk 
is to be taken from. 

Specify operation as: R for Read, W for Write, or * for a Directory 
Write. 

If you do not specify cylinder, the system uses the directory track. If 
you do not specify starting sector, the system starts with sector 0. If 
you do not specify number of sectors, the system reads the whole 
cylinder. 

If an error occurs during a disk function, the error number appears on 
the screen surrounded by asterisks. Hold down the (ENTER) key to 
abort the disk function. 

Example: 

2 *0 *0 *R *6000 *2 (ENTER) 

reads into memory (beginning at address X’6000’) sectors 0 and 1 of 
cylinder 0 from the disk in Drive 2. This block of memory is displayed 
on the monitor in the full screen mode. 


Extended Command Descriptions 

The following commands are available only with the extended 
debugger. 

E (Enter Data) 

E address 


Enter the above command to enter data directly into memory 
beginning at address. The contents of address are displayed and you 
can then type in two hex characters to replace the current contents. 
After typing the byte, press: 






to modify the byte and move to the next address. 


• (ENTER) to modify the byte and exit from the E command. 


• (X) to exit from the E command without modifying the byte 


If you do not specify address, TRSDOS uses the current memory 
modification address (shown by the vertical bars). 
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L (Locate) 

L address, byte 

Enter the above command to locate the first occurrence of byte, 
starting the search at address. 

If you don’t specify address, DEBUG uses the current memory 
modification address (shown by the vertical bars). If you don’t specify 
byte, DEBUG uses the last byte given in a previous L command. 

Example: 

L470E >0D [ENTER) 

searches for the first occurrence of 0D after address 470E. 

N (Next Load Block) 

Enter the above command to position the vertical bars to the next 
load block. This command is used to move logically through a block 
of memory that has been loaded directly from disk using DEBUG. 

To use this command, position the vertical bars over the file type byte 
at the beginning of any block. Press (TD (ENTER) and DEBUG advances 
to the next load block header. 

Example: 

Position the vertical location bars over the beginning byte of a load 
block and type: 

N (ENTER) 

DEBUG advances to the beginning byte of the next load block. 

P (Print) 

P first address, last address 

Enter the above command line to print out the block of memory from 
first address to last address. 

Example: 

PFC80 >FC90 (ENTER) 

prints out the block of memory from FC80 to FC90 in the following 
format: 

aaaa bb bb ... bb cccccccccccccccc 

aaaa represents the current address 

bb bb ... bb represents 16 locations in hex notation 
cccc .... represents the ASCII equivalents of the 16 hex 
locations 
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T (Type ASCII) 

T address 

Enter the above command line to type ASCII characters directly into 
memory, starting at address. If you omit address, DEBUG uses the 
current memory modification address (shown by the vertical bars). 

Example: 

TCB01 (SPACE BAR) 

displays the address CB01 and its current contents in ASCII code. If 
the contents of the address are out of the ASCII character range, then 
a period is displayed. 

DEBUG then prompts you to enter the new ASCII contents for CB01. 
Type: 

A 

to enter the hex value for A, which is 41, in address CB01. 

Pressing (SPACE BAR) advances memory one byte without changing its 
contents. DEBUG continues to prompt you to add ASCII values until 
you press (ENTER) to exit the command. 

V (Compare) 

V first address,second address,length 

Enter the above command line to compare a block of memory 
beginning at first address to the block of memory beginning at 
second address. The compare is for the specified length in bytes 
(X’0001’ — X’FFFF’). 

Example 

UCB00 »EF02 ,a5 (ENTER) 

compares a 45-byte long block of memory beginning at CB00 to a 
45-byte long block of memory beginning at EF02. The first byte of the 
block of memory beginning at CB00 that does not match is displayed 
as the first byte of memory in the DEBUG monitor. The corresponding 
byte in the block of memory beginning at EF02 becomes the current 
memory modification address that is used by the H, A, E, and T 
commands. 

W (Word) 

W address, word 

Enter the above command to search memory for word, beginning at 
address, word must be in the least significant byte, most significant 
byte format. 












If you do not specify address, DEBUG uses the current memory 
modification address. If you do not specify word, DEBUG uses the 
last word given in a previous W command. 

Example: 

WAB0S >3412 (ENTER) 

searches memory for word (1234) beginning at address AB06. The 
address where word is found is displayed in the DEBUG monitor with 
the vertical location bars positioned one byte before it. 


r\ 
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DEVICE 



Advanced Programmer’s Command 

DEVICE [(parameters)] 


Displays the status of the drives, the options selected, and the data 
paths for the logical devices that have been set, routed, or linked. 

It also logs in disks in the available disk drives. 

The parameters are: 

D = NO suppresses the drive portion of the display. Any new 
drives or disks are not detected. 

B=YES enables the logical device portion of the display. 

S=NO suppresses the options status portion of the display. 
P=YES duplicates the display to the printer. 


: 0WP 
: 1 
:2 
s3 
♦KI 

♦ DO 

♦ PR 

♦ SI 

♦ SO 

♦ JL 
Opt 


ETRSDOS603 
C TRSDOS601 
£ No Disk 3 
[No Disk 3 

< = X '08C3 

< = > X ' 0BD0 


Floppy 

Floppy 

Floppy 

Floppy 


• 1 » 
• 2 # 
•a t 
• Q i 


8C3 / ’w 
6D0 ' 

= > X' 0E2E ' 7 2 } 

<= *k i 

= > Nil^ J 3 ) 
ionss Ty fr 


Cyls* 30» Dden» 
Cvls* 40# Dden* 
Cyls= 40# Dden* 
Cyls= 40* Dden* 


Sides=l* Step = 12 ms» Dly»«5s 
Sides=l* St«p*12Ms# Dly=.5s 
Sides=l* SteP s 12MS* Dly».5s 
Sides = l* SteP I 12«s * Dly=.5s 



1. The DRIVE section shows the current configuration of the disk 
drives. 

2. The DEVICE section shows the devices (displayed when B = YES). 

3. The STATUS section displays the status of some user selected 
options. 



:1 CTR5DD5603 5" Floppy «2. Cyls= 40* Dden* Sides»l* Step*12MS* Dly«.5s 
:2 CNo Disk 3 5" Floppy »4» Cyls= 40# Dden* Sides = l» Step=l2«s* Dly*.5s 
:3 ENo Disk 3 5" Floppy «8* Cyls* 40* Dden* Sides=l» Stcp»12MS* Dly*.5s 


1. Logical drive number — The number of the drive accessed. (See 
the SYSTEM command.) 

2. Disk write protect status — The write protect status assigned to 
the drive by the SYSTEM (DRIVE = ,WP = ) command. A disk can 
also be write protected by placing a foil tab over the write-protect 
notch on the diskette. 

WP=Write Protected 

3. Disk name — The name of the disk accessed in the drive. 
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4. Disk size — The size of the floppy or hard disk. 

5. Type of drive — Either floppy or hard. 

6. For floppy disk systems, the physical location of the drive. 

1 - lower 

2 - upper 

4 - middle of the disk expansion cable 

8 - end of cable 

7. Number of cylinders — The number of cylinders available in the 
drive. 

8. Density — The data density of the disk accessed in the drive. 

Dden = Double density 

Sden = Single density 

9. Number of sides — The number of sides the disk being accessed 
has. 

1 = One side 

2=Two sides 

10. Step rate — The step rate of the drive in milliseconds. Step rate 
is the speed at which the disk drive head is moved from cylinder 
to cylinder. 

11. Delay time — The delay time when accessing a 5" floppy disk. 
Delay time is the amount of time the system waits after starting 
the drive motor before it attempts to access the disk. 

NOTE: The Step rate and Delay time are preset for this system. 

Information needed to change these settings can be found in the 

Technical Reference Manual (Cat. No. 26-2110). 


*KI <= X’0893’ 

*DO < = >X’0B8A’ 

*PR = > *l_0: *TD & = > X’0DE8’ 

*SI < = Nil 
*SO <->Nil 
*JL = > Nil 

*FF <#> [Inactive] X’0FD4’ 

*TD < = >PRINT/TXT: 0 
*L0 = >X”0DE8’ 


In the logical device portion of the device table: 

> = indicates an input device 

= > indicates an output device 

< = > indicates a device capable of input and output 

# indicates a filter 

| indicates a link 

If you add a driver or filter to the default system, the DEVICE 
command shows the address where a device transfers control to its 
driver or filter. If more than one filter or driver is associated with the 
same device, the first driver’s address is displayed. It also shows the 
interaction between devices and/or files. 
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Options: Type 

System modules resident: 1, 2, 4, 

The options line shows you the active system parameters. These 
parameters are usually established with the FILTER, LINK, ROUTE, 
SET, SPOOL, and SYSTEM library commands. 

It also shows the resident system overlays. (See the SYSTEM 
(SYSRES = ) library command.) 

Examples 

DEVICE (ENTER) 
displays the device table. 

DEVICE ( D = NO ) (ENTER) 

displays the TRSDOS options, and turns the drive portion of the 
display off. Any new drives or disks are not detected. 

DEVICE ( B = YES ) (ENTER) 

enables the device portion of the device table, and displays the entire 
table. 

DEVICE ( S = NO ) (ENTER) 

displays the drive table, and turns the options status portion of the 
display off. 

DEVICE (P) (ENTER) 

displays the device table, and sends it to the printer. 



1-67 













DIR 



DIR [partspec ] [.drive] [parameters ] 


Command 


Displays the specified disk’s directory. 

You can use DIR to see the files on a disk. 

When you specify a partspec, only those files matching the partspec 
are displayed. 

If you omit the drive number, TRSDOS displays the directories of all 
enabled drives. 


The parameters are: 

ALL displays all directory information for the specified files, 
including space used on the disk. 

INV displays the non-system, invisible files along with the 
non-system visible files. 

MOD displays the files modified since the last backup. 

NON enables the non-stop display mode. 

PRT outputs the directory display to the printer. 

SYS displays the system files along with the visible files. 

DATE displays the files with today’s date. 

DATE = “M1ID1/Y1-M2/D2/Y2" displays the files with modify 
dates between the two specified dates, inclusive. 

= "M1ID1IY1 ” displays the files with modify dates equal to 
the specified date. 

= “-M1ID1IY1” displays the files with modify dates before or 
equal to the specified date. 

= “M7/D7/Y7-” displays the files with modify dates after or 
equal to the specified date. 

SORT = NO specifies that the directory entries are not to be 
sorted alphabetically. 

SORT can be abbreviated to O. 



Drive :0 TRSDOS60 



40 Cy1» DDEN * Free = 



6S.00K / 



100.00K» 



Date 21-Feb-83 


BASIC/CMD P 
CONV/CMD P 
LOG/CMD P 
TAPE100/CMD 


CLICK/FLT P 
FLOPPY/DCT P 
MEMDISK/DCT P 


COh/DVR P 
F0RHS/FLT P 
PATCH/CND P 


COMM/CMD P 
KSM/FLT P 
REPAIR/CMD P 


'*<•) 

D P 


r> 


1. 

2 . 


Drive number. 
Disk name. 


1-68 








3. Number of cylinders on the disk. 

4. Density of the disk. 

DDEN = double density 
SDEN = single density 

5. Free space — The amount of space on the disk currently available 
to the user. 

6. Total free space — The total amount of space (used and unused) 
on the disk. 

7. Creation date — The date on which the disk was created. 

8. Disk files — The disk files are sorted alphabetically. 





Filespec MOD 

Att r 

Prot 

LRL 

• Rees 

EOF 

File Size 

Ext 

Mod Date 

COMM/DVR 

P 

EXEC 

256 

3 

182 

1.50k 

1 

01 -Feb-83 

COMM/CMD 

P 

EXEC 

256 

11 

228 

3.00K 

1 

01-Feb-B3 

CONU/CMD 

P 

EXEC 

256 

6 

196 

1 * 50K 

1 

01 -Feb-83 

FORMS/FLT 

P 

EXEC 

256 

3 

135 

1.50k 

1 

01-Feb-03 

KSM/FLT 

P 

EXEC 

256 

3 

234 

1,50k 

1 

01 -Feb-83 

LOG/CMD 

P 

EXEC 

256 

1 

237 

1.50K 

1 

01 -Feb-83 

MEMDISK/DCT 

P 

READ 

256 

12 

62 

3,00k 

1 

01-Feb-83 

MONITOR/CMD 


FULL 

256 

1 

19 

1,50K 

1 

02-Feb-83 

PATCH/CMD 

P 

EXEC 

256 

10780 

247 

3.00K 

1 

01-Feb-83 

PRINT/DAT 

7 

FULL 

256 

1 

37 

1,50K 

1 

16-Feb-83 

PRINT/TXT 


FULL 

256 

0 

0 

0.00K 

0 


TAMMY/JCL 


FULL 

256 

1 

111 

1,50k 

1 

15-Feb-83 

TESTFILE 


FULL 

256 

0 

0 

0.00k 

0 



13 files out of 31 selected* Space * 21.00K 



1. Filespec — The name and extension assigned to a file when it is 
created. 

2. Modification Status — The modification status of the file. 

+ indicates the file was modified since it was last backed up. 

3. Attribute — The file’s attributes. 

I indicates an invisible file. 

P indicates the file has an owner password. 

S indicates a system file. 

C indicates the file was created with the CREATE library 

command. 

? indicates an open file 

4. Protection Level — The level of access assigned to the user 
password. See the ATTRIB library command for a list of these 
levels. 

5. Logical Record Length (LRL) — The length of each logical record 
in the file. 



6 . 


Number of Records — The number of logical records in the file. 
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7. End of File (EOF) — Shows the last byte number of the file. 

8. File Size — The amount of space in K (1 K= 1024 bytes) that the 
file takes up on the disk. 

9. Extents — The number of extents (blocks of space) that the file is 
stored in. The higher the number, the more fragmented the file is 
on the disk. 

10. Modify Date — The date that the file was created or last written 
to. Since the system uses the date you enter at start-up, we 
recommend that you do not disable the start-up DATE prompt. 

11. Specified Files — The number of files on the disk that match the 
parameters you specify in the command line. 

12. Total Files — The total number of files on the disk. 

13. Space — The amount of space used by the specified files. 
Examples 

DIR (ENTER) 

displays the visible files of all enabled drives. 

DIR : 1 ( I ,S) (ENTER) 

displays all files (visible, invisible, and system) on Drive 1. Specifying 
a drive that is not enabled or ready causes gn “Illegal drive number” 
error message or a [No Disk] message to appear. 

DIR : 1 ( I >S tP) (ENTER) 

sends the directory display of Drive 1 to the printer as well as the 
screen. The NON parameter is automatically set to YES and the 
entire directory prints without pause. Pressing the (SHIFT)!!?)) keys 
pauses the display. Press any key to continue. 

DIR : 2 (A) (ENTER) 

displays the directory of Drive 2 in the allocation format. The display 
pauses after every 24 lines. Pressing (BREAK) terminates the display, 
while pressing any other key displays the next 24 lines. 

DIR (DftTE=" 10/01/82 -” ) (ENTER) 

displays the files modified on or after October 1, 1982. 

DIR (M >S0RT = NQ ) (ENTER) 

displays the files modified since the last backup in an unsorted order. 
DIR B:0 (ENTER) 

displays the files that begin with the letter B on Drive 0. 

DIR T$$T/CMDi 1 (ENTER) 
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9 

displays any file that matches partspec T$$T/CMD on Drive 1. 

DIR -/CMD : 0 (ENTER) 

displays all visible files on Drive 0 except for those that have a CMD 
extension. 




1-71 






DO 



Command 

DO [control character] filespec [(parameters)] [;] 


Compiles and executes a DO file. 

You can use DO to run a file of commands each time TRSDOS starts 
up. 

A DO file is a user created Job Control Language (JCL) file that 
contains one or more library commands. TRSDOS executes the 
commands as if you had typed them in from the keyboard. 

In addition to executing TRSDOS commands, you can load and 
execute user programs from a DO file. 

You can create a DO file with the BUILD command. Command lines 
in this file can include library commands or filespecs. See the Job 
Control Language section for more information on DO files. 

The control characters are: 

$ compiles your DO file without actually executing the 
commands. 

= executes your DO file without compiling it. 

* reruns the last DO command that was compiled. 

When you specify a control character, you must leave a space 
between DO and the character or TRSDOS ignores the character. 

The parameters are: 

@label lets you create JCL files with multiple entry points (an 
entry point is the place where processing begins). A label 
consists of the @ symbol followed by one to eight alphanumeric 
characters. 

parm [ = value] lets you pass value to filespec during execution. 

When you specify the @label parameter, filespec does not execute 
until the label is reached. Execution continues until it reaches the next 
label or the end of the JCL file. 

The @label parameter, by building many different functions into one 
file, reduces the number of individual files on the disk (conserving 
space in the directory). 

Use the semicolon (;) parameter when you need to specify a 
command line longer than 79 characters. 

When a DO command line exceeds 79 characters: 


1. Enclose as many parameters as will fit on one line in parentheses. 
Close the parentheses, insert a (;), and press (ENTER) . 
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2. When a question mark appears on the screen, enter the remaining 
parameters (enclosed in parentheses). 

Examples 

DO DRIVE/JCL (ENTER) 

compiles and executes the file named DRIVE/JCL. 

DO = DRIVE/JCL (ENTER) 

executes the file named DRIVE/JCL without compiling it. 

DO $ DRIVE (ENTER) 

compiles the file named DRIVE/JCL without executing it. Since you 
did not specify an extension to DRIVE, it defaulted to JCL. You can 
LIST the SYSTEM/JCL file to see if the JCL compiled properly. 

DO MY/JCL (OTHIRD) (ENTER) 

compiles and executes the program named MY/JCL. All instructions in 
the program are ignored up to the label (@THIRD). Compilation 
begins at the line following the label and continues until the next label 
or the end of the file is reached. 

DO * CENTER) 

executes SYSTEM/JCL, which contains the last DO file that was 
compiled. 

DO TEST/NEW:2 (D = 5 >E = B) (ENTER) 

compiles and executes the file TEST/NEW on Drive 2. The variable 
parameters D = 5 and E = 6 are passed as needed during compilation. 

Error Conditions 

If you specify @label, you must compile the DO file, or an error is 
generated. 

The occurrence of any error aborts the DO execution. 

When you specify the * control character, a “File not in directory” 
error occurs if there is no previously compiled DO file to rerun. 

When you specify the $ control character, the system compiles the 
JCL file and informs you of any errors that occur. This lets you see if 
the file compiles properly before you actually execute it. When you 
compile a JCL file, a disk in your system must be write-enabled, so 
the system can write the compiled information to a file named 
SYSTEM/JCL. 

When you use the = character, you cannot use some of the JCL 
features. See the JCL section of this manual. 
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Sample Uses 

Suppose you want to set up the following TRSDOS functions to 
execute by typing one command: 

FORMS (MARGIN = 8) 

TIME (CLOCK = ON) 

Use BUILD to create such a file. If you called the file BEGIN, then 
use the command: 

DO BEGIN (ENTER) 


to perform the commands. 






DUMP 



Advanced Programmer’s Command 
DUMP filespec (parameters) 





w 


Copies an area of memory to a disk file named filespec. 

You can use DUMP to store a machine-language program from 
memory to a file. 

DUMP can produce a program or a core ASCII file. A program 
produced with DUMP can then be loaded or executed at any time. 

(An ASCII file cannot be loaded with the LOAD command or executed 
with the RUN command.) 

The default extension for program dumps is /LMF, and the default 
extension for ASCII dumps is /TXT. 

You can use some or all of the following parameters: 

START= address starts the dump at address. You must include 
this parameter. The address must be above 2FFF 
hexadecimal or 12287 decimal. 

END= address ends the dump at address. You must include this 
parameter. END must be greater than or equal to START, 
and can be either a hexadecimal or decimal number. 

TRA = address sets the address at which your program begins 
executing after you load it. If you omit this parameter, any 
subsequent run of the file will only load the program and 
return you to TRSDOS Ready. TRA can be either a 
hexadecimal or a decimal number. 

ASCII specifies that the dump is to an ASCII file. ASCII files 

contain program code only. No system loading information is 
written to filespec. 

ET X=value specifies that the character at the end of an ASCII 
file is equal to value, value is a hexadecimal number in the 
format x’nn’. When you specify ETX, you must also specify 
ASCII. 

ETX cannot be abbreviated. 

When you DUMP to an ASCII file, you create a file that has the 
identical file structure as a SCRIPSIT file. The system writes a special 
character at the end of the file which can be changed with the ETX 
parameter. 

Examples 

DUMP ROUTINE/CMD (START = X'7000' >END = X ' 8000 ' »TRA = 

X '7000 ') (ENTER) 

dumps the area of memory starting at hexadecimal 7000 and ending 
at hexadecimal 8000. This block of memory is written to a disk file 


[ 
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named ROUTINE/CMD. If the file already exists, it is overwritten. If it 
does not exist, it is created on the first available drive. The transfer 
address (starting address for execution) of ROUTINE/CMD is 
hexadecimal 7000. 

DUMP ROUTINE/CMD <START = 28G72 >END=32768 >TRA = 

28672) (ESTER) 

is identical to the above command except that START, END, and 
TRA have decimal values. 

DUMP TEST : 1 < S = X ' 9000 ' »E = X ' BC0F M (JNTER) 

dumps the specified block of memory to a disk file named TEST/LMF 
on Drive 1. Since you did not specify a file extension to TEST, it 
defaulted to /LMF. Also, since you did not specify a transfer address, 
it is written to the file as a return to TRSDOS Ready. 

DUMP WORD/IMG:0 ( S = X'7000'tE = X 'A000 ' * ASCI I) 

(INTER) 

dumps the specified block of memory to a disk file named 
WORD/IMG on Drive 0. Since the ASCII parameter is specified, an 
ASCII file is created. 

DUMP WORD < S = X '7050'tE = X' A000 ' » ETX = X'FF' * 

ASCII) (ENTEff) f — t 

dumps the specified block of memory to a disk file named 
WORD/TXT. An ASCII file is created, and the special character at the 
end of the text (end of text marker) is written as hexadecimal FF. 

Since you did not specify an extension for WORD, it defaulted to 
/TXT. 
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FILTER 



Advanced Programmer’s Command 
FILTER devspec [USING] phantom devspec 


Connects a filter program to devspec which modifies or “filters” data 
as it is read from or written to devspec. 

You can use a filter to change data as it passes from devspec to 
phantom devspec (and vice versa). 

A filter is a program that controls the flow of data to or from any 
device or file. 

devspec is any valid, active TRSDOS device, phantom devspec is 
the name of a device which is connected to the filter program 
established in memory with the SET command. 

You can apply as many filter programs to devspec as you want to. If 
there is not any more space in memory for the filter connection, the 
error message “No device space available” appears. 

*See the SET command for more information on FILTER. 

Example 

Suppose you create a filter program named CONVERT/FLT that 
converts a linefeed character to a “null”, and you establish it in 
memory with the SET library command to a device, *LF. 

FILTER *PR USING *LF (ENTER) 

filters I/O directed to the line printer through the CONVERT/FLT 
program. As a result of this filter program, all linefeed characters in 
output directed to the printer are converted to the null character 
(ASCII 0). 

Sample Use 

You can use a filter to control a printer working with non-standard size 
paper (see Appendix I and the FORMS library command). 
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FORMAT :drive (parameters) 



Utility 


Prepares a blank or old disk for use by defining the tracks and 
sectors and writing system information onto it. (For more information, 
see “Diskette Organization” in the Technical Reference Manual (Cat. 

No. 26-2110).) 

You can use FORMAT to organize a disk so you can store 
information on it. 

drive specifies the drive in which the blank or old disk is to be 
formatted. If you omit the drive, TRSDOS prompts you for it. 

The parameters are: 

ABS overwrites any existing data without prompting. The ABS 
parameter is used primarily when you execute a FORMAT 
from a JCL file. See the JCL section for more information. 

NAME = “d/s/c name” assigns a name to the disk being 
formatted. 

MPW= “password” assigns the master password to the disk. _ 

The master password allows limited access to all user files. 

SDEN specifies the density of the disk as single. 

DDEN specifies the density of the disk as double. 

CYL =number specifies the number of cylinders (tracks) for the 
disk, number can be 35 to 96. 

QUERY = NO turns off the prompts for density, number of 
cylinders, name, and password. 

QUERY is the only parameter that can be abbreviated. 

When to Format 

To prepare a new disk. Before you can use a new disk, you must 
format it. After formatting, record the disk name, date of creation, and 
password. Store this information in a safe place. It helps you estimate 
how long a diskette has been in use. And, if you forget the master 
password, it ensures continued access. 

To erase all data from a disk. To “start over” with a disk, you can 
reformat it. This erases all old information and locks out all flawed 
sectors which have developed. It puts the system information back on 
the disk and leaves the “good” sectors available for information 
storage. 

The Format Prompts 

If the destination drive is not ready, the following message is _ 

displayed: 
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Load destination diskette <ENTER> 


Insert the destination diskette and press (ENTER) to continue, or press 
(BREAK) to return to TRSDOS Ready. 

If you specify the drive number, disk name, or master password in the 
command line, you are not prompted for them. 

If you specify either the DEN or CYL parameters, the system uses the 
default values for the other parameters. 

If you enter a FORMAT command without specifying any parameters, 
you are prompted for them in the following order: 

Which drive is to be used? 

Enter the number of the drive you are formatting in. 

Diskette name? 

Enter any name with up to eight alphanumeric characters. The first 
character must be a letter. Press (ENTER) and the disk name defaults 
to DATADISK. 

Master password? 

Enter any password with up to eight alph anume ric characters. The 
first character must be a letter. Pressing (ENTER) causes the master 
password to default to PASSWORD. 

The remaining prompts concern the type of diskette you are using. 
Press (ENTER) in answer to each of them if you are using standard 
Radio Shack diskettes. 

SinSle or Double density<S»D>? 

Enter CD for single density or CD for double density. Press (ENTER) 
and the value defaults to double density. 

Number of cylinders? 

Enter any number from 35 to 40 on TRS-80 hardware. Pressing 
(ENTER) causes the system to default to the value set with the 
SYSTEM (CYL=) command. If this value is not set, the default is 40 
cylinders. 

If you are formatting in Drive 0, the following prompt appears after 
you answer the cylinders question: 

Load destination disk (ENTER) 

It is important that you do not remove the system disk and insert the 
disk to be formatted until this prompt appears. Several seconds after 
you swap disks, you are prompted to put the system disk back in 
Drive 0 with the message: 

Load SYSTEM disk (ENTER) 
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The format is now complete. 

Examples 




FORMAT (ENTER) 

prompts you for the drive number, the diskette name, the master 
password, the density, and number of cylinders, and checks to see if 
the destination disk is already formatted. 

FORMAT : 1 (NAME= "DATA3" > MPH= 11 SECRET" ) (ENTER) 

prompts you for the DEN and CYL parameters, and checks to see if 
the disk in Drive 1 is already formatted. The disk in Drive 1 is 
assigned the name DATA3 and the master password SECRET. 

FORMAT :0 (NAME*"FILES" t MPW="FILE01"» Q = N) 

center! 

displays the message: 

Load destination disk (ENTER) 

When you insert the destination disk in Drive 0, the system checks to 
see if the disk is already formatted. When the message: 

Load SYSTEM disk (ENTER) 

appears, insert the system disk in Drive 0 and the format is 
completed. 

FORMAT si ( QUERY=NO >ABS) (ENTER) 

formats the disk in Drive 1 (with the default options) even if the disk 
already contains data. Because you specified the ABS parameter, you 
don’t have the opportunity to abort the FORMAT (if the disk is already 
formatted and its master password is PASSWORD). 

Error Conditions 

After you enter a format command and before the actual formatting 
begins, the system checks the destination diskette to see if it is 
already formatted. 

If the disk is formatted and its MPW is PASSWORD, the following 
message appears: 

Disk contains data -- NAME=disK name 
DbTE=mm/dd/yy 

Are you sure you want to format it? 

Press QD to abort the FORMAT or CD to continue. If you specified 
the ABS parameter in the command line, you see the DISK 
CONTAINS DATA message, but you are not prompted to abort the 
format. 
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If the disk is formatted and the master password of the destination 
disk is not PASSWORD, the following message appears: 

Disk contains data -- NAME =disk name 
DbTE = mtr>/dd/yy 

Enter its Master Password or <BREAK> to abort: 

Press (BREAK) to abort the format or enter the master password to 
continue. 

If the disk contains an incomplete or non-standard format, one of the 
following messages may appear in place of NAME = disk name : 

Unreadable directory 

Non-standard forfnat 

Non - i nitia 1ized directory 

When the format begins, you see the cylinder numbers appear as the 
necessary information is written to them. After all cylinders are written, 
FORMAT verifies that the proper information is actually on each 
cylinder. 

If the verify procedure detects an error, an asterisk and the cylinder 
number are shown on the screen. That cylinder is locked out, so that 
no files can be written to the defective area. Use the FREE library 
command to see the locked out cylinders on a diskette. 

During parts of the format operations, the system real time clock is 
turned off. 

If you are formatting in Drive 0, the following prompt appears after 
vou answer the cylinders question: 






FORMS [{parameters)] 


Command 


Sets up forms filter (*FF) parameters. 

You can use FORMS to print a form larger or smaller than a 
standard-size page. 

Before you can use FORMS, you have to SET *FF to its filter 
program FORMS/FLT and FILTER the printer to *FF. See Appendix I. 

The parameters are: 

DEFAULT returns all parameters to their start-up values. 

ADDLF issues a linefeed after every carriage return. 

CHARS = number sets the number of characters per printed line. 
number is 1 - 255. 

FFHARD issues a form feed (Top of Form) character instead of a 
series of linefeeds. 

INDENT= number sets the number of spaces a line is to be 
indented if the line length exceeds CHARS. The default 
value for number is 0. 

LINES= number sets the number of lines to be printed per page. 

The default value for number is 66. 

MARGIN = number sets the left margin. 

PAGE = number sets the physical page size as number of lines. 

The default value for number is 66. 

QUERY prompts you for each parameter. 

TAB specifies that tab characters are to be translated into the 
appropriate number of spaces. 

XLATE = X’aabb’ specifies a one-character translation to be 
performed by the filter. 

aa is the character in hex format to be translated. 
bb is the character in hex format aa is translated to. 


To determine the parameters to set for: 

page size multiply form length in inches by the number of lines 
per inch. 

lines per determine the number of blank lines at the bottom of 
page every page. The default number of blank lines is 0. If 

LINES = PAGE, then text can be written on every line 
of each page. LINES cannot exceed PAGE. 

characters multiply form width in inches by the number of 

per line characters per inch (10 or 12). Use CHARS to set the 

maximum number of printable characters per line. If a 
line is greater than CHARS, then TRSDOS 
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automatically breaks the line at the maximum length, 
and continues printing at the next line. The line is 
indented if you have specified INDENT. 


Examples 

Be sure that you have SET *FF to its filter program FORMS/FLT and 
you have FILTERed the printer to *FF with the commands: 

SET #FF TO FORMS/FLT (ENTER) 

FILTER *PR *FF (ENTER) 

FORMS (ENTER) 

displays the current parameter values. 

FORMS (CHARS = 80 »INDENT = G > PAGE = 51 * 

LINES = 45 >FFHARD) (ENTER) 

allows a maximum of 80 characters per printed line. If a line contains 
more than 80 characters, the excess is printed on the next line and 
indented 6 spaces. The physical page size is set to 51 lines, and 45 
lines can be printed on a page. 

FFHARD causes the printer to advance 6 linefeeds continuously 
rather than individually when the line count reaches 45. Be aware that 
certain printers cannot respond to FFHARD. 

FORMS (MARGIN=10fCHARS = 80>INDENT = 1G) (ENTER) 

causes all lines to start 10 spaces in from the normal left-hand 
starting position. Any line longer than 80 characters is indented 16 
spaces (6 spaces after the margin) when wrapped around, so it is 
printed starting at position 16. 

FORMS (TAB > ADDLF ) (ENTER) 

specifies that tab characters are to be translated into the appropriate 
number of spaces. Also, a linefeed is sent to the printer every time a 
carriage return is sent. 

FORMS (XLATE=X'2A2E' ) (ENTER) 

translates all hexadecimal 2A characters (asterisks) to hexadecimal 
2E characters (periods). 

Sample Uses 

Suppose you have a payroll program that contains all of your 
employees’ payroll information, and that prints checks of the size 4" 
x 7". 

To instruct your computer to print a form 4" x 7", issue the following 
commands: 



















SET *FF TO FQRMS/FLT (ENTER) 

FILTER *PR *FF (ENTER) 

FORMS <CHARS=55>LINES=20*PAGE=24) (ENTER) 

Now when you run your payroll program, you can print the checks on 
the proper size form. 


rs 
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FREE 



Command 

FREE [-.drive] [{parameter)] 


Lists the amount of space that is free (available for use) and the 
number of files on each drive, if no drive is specified. If drive is 
specified, displays a free-space map of the disk in that drive. 

You can use FREE to see how many files are on a disk. You can also 
use FREE to see a table containing information about each disk in 
your computer. 

The parameter is: 

P sends output to the printer. 

FREE displays free-space information about each enabled disk in the 
following format: 




Drive :0 TRSDOS60 
Drive :1 TRSOOS60 
Drive ;2 CNo Disk 
Drive :3 CNo Disk 



02/02/83 Free Space 
02/17/83 Free Space 

] 

] 


TT 



94.50K/ 180.00K Files = 96/128 
91.50K/ 180.00K Files = 97/128 


1. Drive number — The number of the drive whose free space map is 
displayed. 

2. Disk name — The name of the disk. 

3. Date — Creation date. 

4. Free space in K — The amount of space (in K) that is available for 
use. IK = 1024 bytes. 

5. Total space in K — The total amount of space (in K) on the disk. 

6. Number of files — The number of directory entries you have 
available. Each file uses one or more directory slots. 

7. Total number of files — The total number of directory slots 
available on the disk. 
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FREE displays a free space map of the specified disk in the format 
shown below. 




Drive :0 TRSDOSGO 02/02/83 Free Space * 94.50K/ 180.00K Files = 9S/128 


0" 7 X X X .4* 444 444 ... ... ... 
8- 15 .44 X.4 4.4 .44 ..4 XXX XXX 

1G- 23 xxx xxx xxx xxx DDD xxx xxx 
24- 31 xxx xxx xxx xxx xxx xxx x.. 
32- 33 4 4 4 4 . 4 X 4 4 



Type => 5 u Floppy Heads = 1 Density = DOUBLE Note - 1 Position = 1.50K 



1. Disk size — The size of the floppy or hard disk. 

2. Type of drive — Either floppy or hard. 

3. Number of heads — The number of surfaces on the disk that 
contain data for this logical drive. 

4. Density — The density of the disk (SINGLE or DOUBLE). 

5. Note — 1 Position = 1.50 K. — The minimum allocation of disk 
space for the disk type (hard or floppy). This‘value will change 
depending on the type of drive. 

6. Detailed space allocation map — The organization of data on the 
disk. 

The numbers on the left represent the cylinders on the disk, and 
these cylinders are divided into granules (grans). The grans for the 
specified cylinders run across each line. 

Each gran is represented by one of the following characters: 

Unused — The gran is available for use. 

* Locked out — The gran is flawed and not available for use. 

X Used — The gran is currently used for system or user files. 

D Directory — The gran is used for the system’s directory files. 

Examples 

FREE (ENTER) 

displays free space information about each enabled disk. 

FREE : 0 (P) (ENTER) 

displays a free space map of the disk in Drive 0. The map is also sent 
to the printer because you specified the P parameter. 
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LIB 


LIB 


Command 


Displays a listing of all system commands in Libraries <A>, <B>, 
and <C>. 

You can use LIB to see a list of TRSDOS commands. 

Library <A> contains the primary TRSDOS commands, Library <B> 
contains the secondary commands, and Library <C> contains the 
machine-dependent commands. 

Example 

LIB fENTEff) 

displays a list of the TRSDOS library commands. 


Library <A> 



Append 

Copy 

Device 

Dir 

Do 

Filter 

Lib 


Link 

List 

Load 

Memory 

Remove 

Rename 

Reset 


Route 

Run 

Set 





Library <B> 







Attrib 

Auto 

Build 

Create 

Date 

Debug 

Dump 


Free 

Purge 

Time 

Verify 





Library <C> 







Forms 

Setcom 

Setki 

Spool 

Sysgen 

System 



Technical Information 


Library <A> is located in the SYS6/SYS system module, Library 
<B> is located in the SYS7/SYS system module, and Library <C> is 
located in the SYS8/SYS system module. You can remove any of the 
three system modules if you will not be using their commands. (Use 
the PURGE or REMOVE library commands to delete system 
modules.) 
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LINK 




Advanced Programmer’s Command 
LINK devspecl [TO] devspec2 


Links together two logical devices; both must be enabled in the 
system. 

You can use LINK to get a printout of the data displayed on your 
video display. You can also use LINK to write data displayed on the 
screen to a disk file. 

To “unlink” the devices, use the RESET command. 

Be careful if you make several links to the same device. You could 
create an endless loop and hang up the system. 

Examples 

LINK *D0 *PR (ENTER) 

links the video display (*DO) to the line printer (*PR). All output sent 
to the display ( devspecl) is also sent to the line printer ( devspec2 ). 

NOTE: Although all output to the video display is also sent to the 
printer, any output sent individually to the printer (such as an LPRINT 
from BASIC) is not sent to the video display. This is because the 
order of the devices in the link command line is important. Once 
linked, any information sent to devspecl is also sent to devspec2, 
and any information requested from devspecl can also be supplied 
by devspec2. However, information sent to devspec2 is not sent to 
devspecl, nor can information requested from devspec2 be supplied 
by devspecl. 

LINK *PR *D0 (ENTER) 

links the line printer to the video display. All output sent to the printer 
{devspecl) is also sent to the video display (devspec2). 

Linking a Device To a File 

It is not possible to directly LINK a device to a file. To link a device to 
a file, follow this procedure: 

• Use the ROUTE library command to create a “phantom” 
device and route it to the file. 

• Link the device to the phantom device using the LINK library 
command. 

NOTE: Do not use the SYSGEN library command if you currently 
have a device linked to a file. The linked file is shown as open every 
time you power up or reset the system. You can overwrite other files 
very easily if you switch disks with the linked file open. 
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The following example shows how to link your line printer to the disk 
file PRINT/TXT on Drive 0 using a phantom device. 

ROUTE *DU TO PRINT/TXT;0 (ENTER) 

creates the phantom device *DU and routes it to the disk file 
PRINT/TXT on Drive 0. If PRINT/TXT does not exist, it is created. If it 
already exists, data sent to the file is appended onto its end. 

LINK *PR *DU (ENTER) 

links the printer to *DU, which in turn is routed to PRINT/TXT. All 
output sent to the line printer is also sent to *DU (that is, written to 
PRINT/TXT). 

NOTE: PRINT/TXT remains open until you issue a RESET *DU 
command. To break the link between the printer and PRINT/TXT 
without closing the file, use the RESET *PR command. See the 
ROUTE and RESET library commands; also see the “Using the 
Device-Related Commands” section. 

Sample Use 

Suppose you want to use your computer to communicate with another 
computer. First, set the Communications Line device (*CL) and use 
SETCOM to specify WORD = 8 and PARITY = NO with the 
commands: 

SET *CL TO COM/DUR (ENTER) 

SETCOM (WORD = 8 >PARITY = NO) (ENTER) 

then issue commands: 

LINK *D0 *CL 
LINK *KI *CL 

to link the video display and keyboard to the RS-232C interface. This 
lets your Model 4 act as a “host" and be accessed by a remote 
terminal via the RS-232C hardware. 
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LIST 



Command 


LIST filespec [{parameters)] 


Lists the contents of filespec. 

You can use LIST to see the contents of a file on a disk. 

The parameters are: 

ASCII8 displays the graphic characters and special characters in 
a file, along with the text. 

NUM numbers the lines in ASCII text files. 

HEX specifies hexadecimal output format. When you specify the 
HEX parameter, NUM and LINE are ignored. 

TAB = number specifies that tab stops are to be placed every 
number of spaces apart for ASCII text files. Each tab 
character (hex 09) encountered causes a jump to the next 
tab stop. The default value for number is 8. 

P directs output to the printer. 

LINE= number sets the starting line to number. If you omit the 
LINE= parameter, TRSDOS uses 1. This parameter works 
only with ASCII files. 

REC = number sets the starting record number to number. If you 
omit the REC= parameter, TRSDOS uses 0. The REC = 
parameter is used only with the HEX parameter. 

LRL =number sets the logical record length to be used to display 
a file with a record length of number. If you omit the LRL = 
parameter, TRSDOS uses the logical record length of the 
file. The LRL= parameter is used only with the HEX 
parameter. 

LINE cannot be abbreviated, and the abbreviation for ASCII8 is A8. 

When you enter a LIST command, LIST first searches for 

filename/ TXT. If it cannot find filename/ TXT, it searches for filename. 

Press (MED® to pause a list. Press (ENTER) to continue. Press 

(BREAK) to abort the list. 

When you use the HEX parameter, filespec is listed in the following 

format: 





0000:00 = 41 42 43 44 45 4G 47 46 49 4A 4B 4C 4D 4E 4F 50 ABCDEFGH IJKLMNOP 


51 52 53 54 55 5G 57 58 59 5A 0D 


1. Current logical record of the file in hex notation, starting with 
record 0. 
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2. Offset from the first byte of the current logical record (in hex 
notation). 

3. Hex representation of the byte listed. 

4. ASCII representation of the byte. A period is used for all 
non-displayable bytes. 

Examples 

LIST TESTFILE ; 0 (ENTER) 

searches Drive 0 for TESTFILE/TXT. If not found, it searches for 
TESTFILE. 

LIST MON ITQR/CMD (HEX >LRL = 8) 

lists MONITOR/CMD in the hexadecimal mode using an LRL of 8. 

LIST REPLY/TXT (NUM >TftB = 10 >P) (ENTER) 

prints a listing of REPLY/TXT on the printer, numbering each line that 
is printed. Lines are numbered beginning with 00001. Any tab 
character encountered causes a jump to the next tab position (every 
10th column). 

LIST TESTFILE/OBJ (HEX >REC = 5) (ENTER) 
list TESTFILE/OBJ in the hex mode, beginning with record 5. 

Sample Use 

Suppose you used BUILD to create a file named HEXFILE/TXT which 
contains hexadecimal characters that are not available from the 
keyboard. Issue the command: 

LIST HEXFILE/TXT (ENTER) 

and the special characters are displayed on the screen. 



Advanced Programmer’s Command 
LOAD [(parameter)] filespec 


Loads a machine-language program file (without executing it) and 
then returns to TRSDOS Ready. 

You can use LOAD to pre-load assembly language routines that 
programs written in a language such as BASIC can call. 

The parameter is: 

X loads a file from a non-system disk. 

The file must be in load module format. Do not use it to load BASIC 
program files. The default file extension for the LOAD command is 
/CMD. 

Programs to be loaded must reside at or above the address X’3000’. 

Examples 

LOAD STATUS/CMD (ENTER) 

loads the file STATUS/CMD into memory. 

LOAD (X) PROGRAM/C IM (ENTER) 

loads PROGRAM/CIM from a non-system disk. The system prompts 
you to insert the disk with the desired file on it with the message: 

Insert SOURCE disK (ENTER) 

After the file is loaded, you are prompted to put the system disk back 
in Drive 0 with the message: 

Insert SYSTEM disk (ENTER) 

The load is now complete. 

Sample Use 

Often several program modules must be loaded into memory for use 
by a master program. For example, suppose PAYROLL/PT1 and 
PAYROLL/PT2 are modules, and MENU/CMD is the master program. 
Then you could use the commands: 

LOAD PAYROLL/PT 1 (ENTER) 

LOAD PAYR0LL/PT2 (ENTER) 

to get modules into memory, and then type: MENU to load and 
execute MENU. 


r\ 
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LOG/CMD 


Utility 


LOG/CMD is used in Radio Shack hard disk installations. See your 
hard disk manual for an explanation on how to use this utility. 
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MEMORY 




Advanced Programmer’s Command 

MEMORY [(parameters)] 


allows you to reserve a portion of memory, display or change the 
current HIGH$ and LOW$, modify a memory address, or begin 
executing at a specified memory location. HIGH$ has to be higher 
that LOW$. 

You can use MEMORY to find out which area of memory you can 
use. 

The parameters are: 

CLEAR = value fills memory from hex 2600 to HIGH$ with value, 
value in the format X’nn’. If you do not specify value, 
memory is filled with the hexadecimal value 00 (null). 

HIGH = address sets address as HIGH$. address must be less 
than the current HIGH$. 

LOW= address sets address as LOW$. If you specify LOW, the 
current LOW$ is displayed. 

Note: Subsequent MEMORY commands (and any other system 
level commands) will reset LOWS to its default value. 

ADD = address displays the word at address and specifies the 
address of WORD and BYTE. If you Specify ADD, the 
current contents of the address are displayed and WORD 
and BYTE are not necessary. 

WORD = word changes the contents of ADD and ADD + 1 to 
word. 

BYTE = byte changes the contents of ADD to byte. 

GO = address transfers control to address. If more than one 
parameter is specified, the GO parameter is always 
executed last. 

address is any memory address in hexadecimal or decimal notation. 
word is any value in the range 0000 - FFFF hexadecimal or 0 - 
65535 decimal, byte is any value in the range 00 - FF hexadecimal or 
0 - 255 decimal. 

Examples 

MEMORY (ENTER) 

displays HIGH$ (the highest unused memory location) and LOW$ (the 
lowest reserved memory location) in the hexadecimal X’nnnn’ format. 

MEMORY (HIGH = X ' E100 7 ) (ENTER) 

sets HIGH$ to hexadecimal memory address El 00, as long as the 
existing HIGH$ is above X’E100’. The MEMORY command moves 
HIGH$ lower in memory. 
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MEMORY (ADD = X'G500 ') jNTlR) 





displays the contents of hexadecimal memory addresses 6500 and 
6501 in the following format: 

X'6500' = 2585G <X'G745') 

HiSh = X ' E100 ' Low = X'2FFF' 

1 The address specified in hexadecimal notation. 

2 The decimal equivalent of the address. 

3 The contents of address and address + 1, in MSB-LSB format. 

4 The current HIGH$ address. 

5 The current LOW$ address. 

MEMORY (ADD=X'E100' »WORD=X / 3E0A') (ENTER) 

modifies hexadecimal memory locations ADD (El00) and ADD + 1 
(El 01), changing them to the value of WORD. The following display 
appears: 

X 'E100 ' = 57G00 (X'0000' => X ' 3E0A ' ) 

Hisfh = X ' E100 ' Low = X'2FFF' 

1 The address specified in hexadecimal notation. 

2 The decimal equivalent of the address. 

3 The new contents of address and address + 1, in MSB-LSB 
format. 

4 The current HIGH$ address. 

5 6The current LOW$ address. 

MEMORY (ADD = X , E100' »BYTE = X'C8') (ENTES 

changes the BYTE of memory at hexadecimal address El 00 to 
hexadecimal C9. The display after executing this command is: 

X ' E100' = 57G00 (X'00' => X'C9 ' ) 

HiSh = X'E100 ' Low = X'2FFF' 

The display is identical to the last example, except that the modified 
BYTE is shown instead of the modified WORD. 

MEMORY (GQ"X'E100' ) (ENTER) 

transfers control to hexadecimal memory address El 00. 

Error Conditions 

If you set LOW$ equal to or higher than HIGH$, you get the error 
message “Range error.” 


m 
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4 * 

Lets you make minor corrections in any disk file by (1) typing in the 
patch code directly from the command line (Method A), or (2) creating 
an ASCII file containing patch information (Method B). 

You can use PATCH to make minor corrections in any disk file. 

You can use PATCH to make minor changes in your own 
machine-language programs. You need not change the source code, 
reassemble it, and recreate the file. You can use PATCH to make 
minor replacement changes in data files, also. 

Method A 


Advanced Programmer’s Utility 
PATCH filespec (patch commands) 


Makes minor corrections in filespec by letting you type in the patch 
code directly from the command line. You can use only the address 
patch command for this type of patch. 

Method B 


Advanced Programmer’s Utility 
PATCH filespecl USING filespec2 [(parameters)] 




Makes minor changes (which are contained in filespec2) to filespecl. 

filespecl is the file to be changed and /CMD is its default extension. 
filespec2 contains the patch commands. filespec2 can contain only 
ASCII characters and /FIX is its default extension. 

The patch commands are: 

address = value identifies the PATCH as a patch by “memory 
load location.” It changes the contents of memory beginning 
with address to value. 

Drecord,byte = value identifies the PATCH as a “direct modify 
patch.” record tells which record contains the data to be 
changed. It is a hexadecimal number from 00 to FF. byte 
specifies the position of the first byte to be changed. It is a 
hexadecimal number from 00 to FF. 

Frecord,byte = value lets you make sure that a patch is applied 
to the correct place in memory, when used in conjunction 
with the D patch command. F record,byte follows 
Drecord,byte. If the location specified with the D patch 
command does not contain the data specified with 
F record,byte , then the PATCH aborts. F record,byte is also 
used with the REMOVE parameter to remove a patch and 
replace it with the original data. 

Lcode identifies the PATCH as a “library mode patch.” The 
PATCH applies to either the SYS6/SYS, SYS7/SYS, or 
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SYS8/SYS library command module, code is the binary 
coded location in the format nn where the change begins. 

address is a four-digit hexadecimal value in the format X’nnnn’ which 
is the memory load address for the change. 

value can be either a series of hexadecimal bytes in the format nn nn 
nn..., or a string of ASCII characters in the format "string.” 

The parameters are: 

YANK removes the PATCH specified by filespec2 from filespecl. 

The specified PATCH contains code in the address format. 
REMOVE removes the PATCH specified by filespec2 from 
filespecl. The specified PATCH contains code in the 
^record,byte format. 

An address patch command changes a file by “memory load 
location.” It adds the patch code to the end of the filespec and then 
makes the changes beginning at address each time the file is loaded. 
You can use YANK to remove the added code from filespec. This 
type of patch can be applied only to files that can be loaded with the 
LOAD or RUN library command. 

A Drecord,byte:Frecord,byte patch command changes a file by 
“direct modify patch.” It changes a file by directly applying the patch 
code to the specified record and byte of filespec. When you BUILD a 
file containing patch commands in this format, you can REMOVE the 
patch. 

An easy way for you to find the record and byte of filespec that you 
want to patch is to list filespec using the LIST library command with 
the HEX parameter. Remember that the first record in a file is record 
0, not record 1. 

Lcode patch command patches are supplied by Radio Shack for you 
to implement changes to TRSDOS. You have to BUILD a patch file to 
apply this type of PATCH. 

You can specify more than one line of patch code from the command 
line by placing a colon (:) between the lines of patch code. 

Examples 

These examples are used to show the syntax and development of the 
PATCH command, so do not execute them. 

PATCH MONITOR/CMD (X'E100'=C3 G6 00 CD 03 40) 

(ENTER) 

patches the file MONITOR/CMD by the memory load location method. 
The six bytes beginning at hexadecimal El 00 are changed. During 
the PATCH operation, the following message is displayed: 

Instal1ina patch 

When the operation is completed, this message appears: 

Patch function completed 
x patch lines installed 
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x is the number of lines of patch code that were installed. 

Since there is no filespec used for the patch code, the name CLP 
(Command Line Patch) is assigned to the patch code. You can use 
this name to later YANK the patch from MONITOR/CMD. 

Error Conditions 

It is important that you do not patch a file more than once using the 
same name for filespec2 because you cannot YANK the second 
patch from the file. 

We recommend that you name all patch files in a systematic manner 
and that you use the extension /FIX for all of the files. 

Using BUILD To Create a PATCH File 

You can use the BUILD library command to create a PATCH file. 

(See the “Building a File” section of the BUILD library command.) A 
PATCH file can contain only ASCII characters. 

Each line in a patch file is either a patch command or a comment. 
Comment lines begin with a period and are ignored by the patch 
utility. Use comments in patch files to document the changes that you 
make. You can append a comment onto the end of a patch command 
by using a semicolon to separate the two parts. 

You can also use SCRIPSIT to create a PATCH file. When you create 
a PATCH file with SCRIPSIT, use the S,A type of save. SCRIPSIT 
sometimes leaves extra spaces after the last carriage return in a file. 
To remove the extra spaces, position the cursor just after the last 
carriage return in the file and do a delete to end of text. 

Examples 

These examples are used to show the syntax and development of the 
PATCH command, so do not execute them. 

PATCH BACKUP/CMD : 0 USING SPECIAL/FIX (ENTER) 

The data in BACKUP/CMD on Drive 0 is changed to 23 3E 87 
beginning at hexadecimal 6178. The data beginning at hexadecimal 
61A0 is changed to FF 00 00. This is an example of a memory load 
location patch, and since the patch is added onto the end of 
BACKUP/CMD, you can use the YANK parameter to remove it. 

Use the BUILD library command to create the following PATCH file 
named TEST/FIX: 

.This patch modifies the SYS2 module. 

D0B,49 = EF CD 44 65:F0B,49 = DD 3A 33 44 
DOB,55 = C3 00 00:F0B,55 = EF 44 55 
.End of patch 

Now, type in the command line: 

PATCH SYS2/SYS.PASSWORD USING TEXT/FIX (ENTER) 


1-98 












changes the data specified in SYS2/SYS.PASSW0RD to the data in 
TEST/FIX. Since the data beginning at record 0B, byte 49 and 55 is 
directly changed on disk, this is an example of a direct disk modify 
patch. The Find patch commands let you make sure you are patching 
the correct place in memory. 

Using PATCH on a TRSDOS System File 

When Radio Shack releases a modification to TRSDOS, you receive 
a printout of the exact patch commands that you must use to make 
the change. 

Suppose Radio Shack sends you the patch information for a file 
named LIB1 that contains the following patch code: 

.USE LIB1 TO PATCH SYS6/SYS. 

L54 

X’5208’ = 32 20 DE AF 00 C3 66 00 

Use the BUILD library command to create the file LIB1, and type in 
the lines exactly as they appear on the printout. After you end the file, 
type in the command line: 

PATCH SYSB/SYS: 1 USING LIB1 (ENTER) 

This changes the data specified in SYS6/SYS on Drive 1 to the data 
in LIB1/FIX. Since you did not specify an extension to LIB1, it 
defaulted to /FIX. This patch is in the memory load location mode. 
Library patches can also be done with the direct disk modify mode. 

To be sure that you do not patch the disk in Drive 0, specify the drive 
number in the filespec (such as SYS6/SYS:2) or write protect the disk 
in Drive 0. 

PATCH lets you implement any changes to TRSDOS that may be 
supplied by Radio Shack. This way, you do not have to wait for a new 
release of TRSDOS. 

To make a Radio Shack change, follow these general steps: 

1. Make a backup copy of the diskette to be patched. 

2. Insert the TRSDOS diskette to be changed into one of the drives. 
(Make sure the diskette is “write-enabled.”) 

3. In the TRSDOS mode, use the BUILD library command to create a 
PATCH file containing the patch commands specified in the 
information provided by Radio Shack. 

4. Issue the appropriate PATCH command. 

5. After the patch is complete, test the patched diskette in Drive 0 to 
see that it is operating as a TRSDOS system diskette. You have to 
reset the computer before you can test the diskette. 
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Command 


PURGE [partspec]:drive [(parameters)] 


Quickly deletes files from the disk in drive. 

You can use PURGE to remove all or some of the files on a disk with 
one command. 

The parameters are: 

QUERY = NO automatically removes files without prompting for 
each one. 

MPW ^“password'’ states the disk master password 
INV removes the invisible files as well as the visible files. 

SYS removes the system files as well as the visible files. 

DATE = “MlID1IY1-M2/D2/Y2" removes the files with modify 
dates between the two specified dates, inclusive. 

= “M1/D1/Y1” removes the files with modify dates equal to 
the specified date. 

= “-M1/D1/Y1” removes the files with modify dates before or 
equal to the specified date. 

= “M1ID1/Y1-" removes the files with modify dates after or 
equal to the specified date. 

Once you enter the PURGE command, TRSDOS prompts you for the 
disk’s password (if it is not PASSWORD), unless you specified it with 
the MPW parameter. 

Then, the system displays the files one at a time. It prompts you to 
remove the file or keep it. Respond with (X) to remove the file or QD 
to keep it. Pressing (ENTER) skips the file. 

NOTE: BOOT/SYS and DIR/SYS cannot be purged and do not 
appear during execution of any PURGE command. 

Examples 

PURGE : 0 ( MPM= 11 SECRET " ) (ENTER) 

purges all visible files on Drive 0 if the master password of the disk is 
SECRET. If SECRET is not the master password, the purge aborts 
with an error message. The purge shows each file and waits until CD, 
CD, or (ENTER) is pressed before displaying the next file. 

PURGE : 1 (QUERY = NQ > INU >SYS ) (ENTER) 

purges ALL files from Drive 1. You are not questioned before each file 
is removed, as QUERY is specified as NO. Be careful with this 
command because it produces a blank formatted disk. 

PURGE /BAS : 1 (Q = NO) (ENTER) 
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purges all visible files with the extension /BAS. You are not 
questioned before each file is removed, as QUERY is specified as 
NO. 


PURGE /$$S:2 


Ml 


purges all visible files on Drive 2 whose file extension contains 3 
characters and ends in the letter S. 


PURGE -/CMD:0 (INV) (ENTER) 


purges all non-system files from Drive 0 except those with the 
extension /CMD. 


PURGE : 1 (DflTE = 11 02/01/81-" ) (ENTER) 


purges all visible files on Drive 1 with modify dates of February 1, 
1981 or later. You are questioned before each file is removed. 

Sample Use 

Refer to the Sample Use example in the BACKUP command section. 
Now that you have moved all of the new files to the disk in Drive 1, 
you can remove all the new files on the disk in Drive 0 by issuing the 
command: 


PURGE /NEW:0 


G3HD 


Now you have two separate disks: one with new employee files on it 
and one with old employee files on it. 
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REMOVE 



REMOVE filespec [i filespec ...] 

Command 

Deletes filespec from the directory and frees the space allocated to it. 

REMOVE devspec [devspec ...] 

Command 


Removes devspec from the device table. 


You can use REMOVE to remove a file that you don’t need to use 
anymore. You can also REMOVE a device that is no longer needed. 

Examples 

REMOVE ALPHA/DAT : 0 BREAKER/DAT : 0 (ENTER) 

deletes ALPHA/DAT and BREAKER/DAT from the directory on Drive 
0 and frees all space allocated to them. 

REMOVE MIDUEST/DAT. SECRET (ENTER) 

deletes MIDWEST/DAT. If the file is protected at a level of RENAME 
or higher, the owner password must be used to remove the file. If you 
supply the user password, the error message “Illegal access 
attempted to protected file” is displayed. If you supply the wrong 
password, the error message “File access denied” is displayed. 

REMOVE *LU (ENTER) 

removes the user-created device *LU from the device table. 

NOTE: A device can be removed only if it is pointed NIL in the device 
table. If a device is not pointed to NIL, it must first be reset with the 
RESET library command before it can be removed. 

TRSDOS does not permit the removing of the system devices: *JL, 
*KI, *DO, *SI, *SO, and *PR. Attempting to remove these devices 
produces the error message “Protected system device.” 

Sample Use 

Suppose you have a file of temporary employees that you hire for 
inventory. All of the temporary employees’ files are in a file named 
EMPLOYE/TEM. When you complete inventory, you can remove this 
file with the command: 

REMOVE EMPLOYE/TEM (ENTER) 
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RENAME 



Command 

RENAME filespecl [TO] filespec2 
RENAME devspecl [TO] devspec2 



Changes a file’s name and/or extension from filespecl to filespec2. It 
also changes a device name from devspecl to devspec2. 

You can use RENAME to change the name of a file or a device. 

RENAME does not change the file’s password, contents, or position 
on the disk. (See the ATTRIB command to change the password.) If 
filespecl is password protected, the password must be specified or 
an error message will result. 

RENAME does not change a device’s routing, filtering, linking, or 
setting, devspecl must be an existing device, and devspec2 must be 
an unused device name. 

You cannot RENAME the system devices: *KI, *DO, *PR, *SI, *SO, 
and *JL. 

Examples 

RENAME TEST/DAT : 0 TO OLD/DAT (ENTER) 

renames TEST/DAT on Drive 0 to OLD/DAT. 

RENAME TEST/DAT: 0 TO REAL (ENTER) 

renames TEST/DAT on Drive 0 to REAL/DAT. Since you did not 
specify an extension for filespec2, it defaulted to the extension on 
filespecl (DAT). 

RENAME TEST/DAT : 0 TO REAL/ (ENTER) 

renames TEST/DAT on Drive 0 to REAL (without an extension). 

RENAME DATA/NEW.SECRET: 1 TO /OLD (ENTER) 

renames the password protected DATA/NEW.SECRET on Drive 1 to 
DATA/OLD.SECRET. Since you did not specify a filename for 
filespec2, it defaulted to that of filespecl. RENAME does not change 
or delete passwords, so the password defaulted also. 

RENAME *UD TO *TX (ENTER) 

renames the device *UD to *TX. 

Error Conditions: 

Suppose you want to rename TESTER/BAS to TESTER (without an 
extension). Typing: 

RENAME TESTER/BAS TO TESTER (ENTER) 
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produces the error message “Destination spec required” because you 
did not add a “/” to TESTER. 


Suppose you want to rename TEST/JCL to TEST/ABS, but the file 
TEST/ABS already exists. Typing: 

RENAME TEST/JCL TO TEST/ABS CENTER) 

produces the error message “Duplicate file name” because 
TEST/ABS already exists. 
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REPAIR (REPAIR/CMD) 


REPAIR :drive 


Utility 



Updates and modifies information on floppy disks produced on other 
Radio Shack operating systems and computers so TRSDOS Version 
6 can use them. 

drive is any floppy drive currently enabled in the system (except 
Driye 0). 

After REPAIR is complete, you should be able to copy any file off the 
modified diskette. 

Use REPAIR to read any disk formatted by any disk operating system 
other than TRSDOS Version 6, LDOS 5.1.3, or their successors. 

Once a disk is modified by TRSDOS, the operating system that 
created it may not be able to read it. 

TRSDOS 1.2 and 1.3 disks should NEVER be repaired. Use the 
CONV utility to copy programs from them. 

Using REPAIR, you can convert the following list of operating system 
diskettes to TRSDOS Version 6 diskettes: 

• Model I TRSDOS 2.0, 2.1, 2.2, 2.3, 2.3a 

Examples 

REPAIR : 1 (ENTER) 

updates information on the diskette in Drive 1 so that TRSDOS can 
use it. 
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RESET 



Advanced Programmer’s Command 

RESET devspec 
RESET filespec 


Returns a devspec to its original start-up condition. Closes an open 
filespec. 

You can use RESET to set a system device to its normal condition in 
the DEVICE table. You can also use RESET to close a file that has 
not been properly closed. 


Resetting a Device 

A RESET devspec command removes any filtering, linking, or routing 
that has been set to the device. Any open disk file that is connected 
to the device is closed. 

If devspec is a device you created (see the LINK and ROUTE library 
commands), it is pointed at NIL when reset. 

If devspec is a system device (*KI, *DO, *PR, *SI, *SO, and *JL), it 
returns to its start-up condition when reset. 

To see that devspec has been pointed at NIL or returned to its 
start-up condition, issue a DEVICE library command and examine the 
device table that is displayed. 

You can use the REMOVE library command to remove the device 
from the device table once it points at NIL. 

Example 

Suppose you have used the FORMS command to specify printer 
parameters, or you have filtered, linked, or routed *PR. 

RESET *PR (ENTER) 

returns *PR to its start-up condition and disconnects the printer filter. 



Resetting a Filespec 

You can RESET an open filespec that has not been properly closed. 

Improperly closed files result when (1) your system loses power and 
files are left open, (2) you remove a disk from a drive and files are left 
open, or (3) you reset your system while files are open, or (4) a 
command aborts while files are open. 

To see if any files on a disk are not properly closed, issue a DIR 
library command. Any file that appears with a question mark (?) after 
it needs to be RESET before you can access it. Receiving the error 
“File already open” may also indicate a file is not properly closed. 
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Example 

Suppose that your system lost power and there is a file named 
PRINTER/DAT that is not properly closed. 

RESET PR I IMTER/DftT (ENTER) 

closes the file named PRINTER/DAT and lets you access it. 
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ROUTE 


rs 


Advanced Programmer’s Command 
ROUTE devspecl [TO] devspec2 
ROUTE devspecl [TO] filespec [(REWIND)] 

ROUTE devspecl (NIL) 


Routes devspecl to one of the following: 

• another device (devspec2) 

• a disk file (filespec) 

• nothing (NIL) 

You can use ROUTE to create a device. You can also use ROUTE to 
alter the flow of data from one device to another. 

If devspecl does not already exist, ROUTE creates it. 

To see how your devices are routed, use the DEVICE command. To 
return the non-system devices to their normal start-up state, use the 
RESET and REMOVE commands. 

Examples 

ROUTE *PR *D0 

routes the printer (*PR) to the video display (*DO). All data normally 
sent to the printer will be displayed on the screen. 

ROUTE *PR TO PRINTER/DAT 

routes the printer (*PR) to a disk file (PRINTER/DAT). All data 
normally sent to the printer will be stored in a disk file named 
PRINTER/DAT. If PRINTER/DAT already exists, the data is appended 
to the end of the file. 

RESET *PR 

closes the PRINTER/DAT file and any subsequent output to *PR 
goes to the printer. The PRINTER/DAT remains open until you 
execute the above command. 

ROUTE *PR TO PRINTER/DAT (REWIND) 

routes the printer to PRINTER/DAT. If PRINTER/DAT already exists, 
the system “rewinds” the file to the beginning. The contents of the file 
will be replaced with the new printer data. 

ROUTE *PR (NIL) 

routes *PR to NIL. TRSDOS ignores all output to the printer. 

ROUTE *DU TO TEST/TXT:1 

routes a user device (*DU) to a disk file named TEST/TXT in Drive 1. 



'"'N 
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Error Condition 

If you ROUTE *CL to a file and you are receiving data from a 
communications line (*CL), you might lose data if it is coming in at a 
high speed. If so, use CREATE to preallocate file space before using 
ROUTE. This makes data loss less likely because the system no 
longer has to spend the time allocating more space. 

Sample Use 

Suppose you want to route a report-producing program to a file 
(instead of printing the report). Issue the command: 

ROUTE *PR TO REPORT/DAT (ENTER) 

Now you can run the program and the report that it produces is 
routed to the file REPORT/DAT. This means that you can print the 
report in the file REPORT/DAT whenever you want by using the LIST 
command. 

NOTE: Remember, you must reset *PR before listing the file so that it 
will be properly closed. 


» 
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Command 




[RUN] [( parameterl )] filespec [(command text)] 


Loads a program named filespec into memory and executes it. 

You can use RUN to execute a program. 

Typing RUN is optional. You can load and execute a program from 
the TRSDOS Ready prompt by simply typing in the name of the 
program (without the RUN). 

The default extension for filespec is CMD. 

Parameterl is: 

X executes a program from a non-system disk for the single 
drive user. 

Command text is an optional value which the program you specified 
may require. 

When running a program, observe the following address restrictions: 

RUN filespec must load above X’2FFF’. 

RUN (X) filespec must load above X’2FFF’. 

Examples 

RUN CONTROL/CMD (ENTER) 

loads a program named CONTROL/CMD and executes it. 
CONTROL/CMD (ENTER) 

loads a program named CONTROL7CMD and executes it. 

RUN PROG (ENTER) 

loads a program named PROG/CMD and executes it. Since you did 
not supply a file extension, it defaulted to /CMD. 

RUN (X) TRftDERS/CMD : 0 (ENTER) 

loads TRADERS/CMD from a non-system disk. First you are 
prompted with the message: 

Insert SOURCE disk (ENTER) 

Insert the disk containing the program into Drive 0 and press (ENTER) . 
After the program is loaded into memory, you are prompted with: 

Insert SYSTEM disk (ENTER) 

Insert the system disk back into Drive 0 and press (ENTER) : program 
execution begins. 
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SET 



Sets a driver or filter program to a device. This command is for 
advanced programming applications. 

You can use SET to tell TRSDOS the name of a filter or driver 
program that you are going to use. 

A driver program channels data to or from a device. If it is outputting 
to a device, it converts data to the device’s format. If it is inputting 
from a device, it converts the data to the computer’s format. 

A filter program filters data before it is sent out or after it is received. 

Once the device is SET, it remains SET until it is RESET. You cannot 
SET an active device. 

Setting a Driver Program 


Advanced Programmer’s Command 
SET devspec [TO] driver filespec [(parameters)] 


Loads driver filespec into memory and sets it to devspec. The driver 
filespec can be one of your own driver programs. 


Once you set a system device to a driver, the device is controlled by 
your own driver program, rather than the TRSDOS driver program. 


The parameters are values sent to the driver filespec. These 
parameters are totally independent of the SET command. They are 
determined only by the needs of your driver program. 


Example 

Within TRSDOS is a driver program that sends printer output to the 
parallel port. Suppose you write a driver program named 
SERIAL/DVR that sends printer output to the serial port. 


SET *SP TO SERIflL/DUR (ENTER) 


loads SERIAL/DVR into memory and sets it to the device *SP. 
ROUTE *PR TO *SP (ENTER) 


routes data going to the printer to the device *SP. Now any input to 
the printer goes to the SERIAL/DVR program. The SERIAL/DVR 
program, in turn, sends the output to the serial port. 

By using a LINK command instead of the ROUTE compiand, data 
sent to *PR is sent to the TRSDOS parallel printer driver. It is also 
sent (via the LINK) to the serial driver and then to the serial printer. 
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Setting a filter program 



Advanced Programmer’s Command 
SET phantom devspec [TO] filter filespec [USING] 
[parameters] 


loads the driver or filter specified by filter filespec into memory and 
connects it to phantom devspec (a non-existing device). You must 
then use the FILTER command to connect the phantom device to a 
real device. 

The filter filespec can be the KSM/FLT program (listed in Appendix I) 
or one of your own filter programs. 

Once you have (1) set a phantom device to a filter, and then (2) 
filtered a device to the phantom device, the device is connected to 
your filter program. All data input and output to the device is filtered 
through your program. 

The parameters are values sent to the filter program. These 
parameters are totally independent of the SET command. They are 
determined only by the needs of your filter program. 

Example 

Suppose you write a filter program named TRAP/FLT to change some 
characters sent to *DO, the video display. 

First, you need to load your TRAP/FLT program and set it to a 
phantom device (this example uses *LC as the name of the phantom 
device): 

SET *LC TO TRAP/FLT 
This causes *LC to point to TRAP/FLT. 

Then, you need to use *LC (which points to the TRAP/FLT program) 
to filter the data output to the video display: 

FILTER *D0 *LC (ENTER) 

Now, all data output to the video display is filtered through your filter 
program. 

SET *DU KSM/FLT USING FILEDAT/KSM (ENTER) 

FILTER *K I *DU [ENTER) 

loads the Keystroke Multiply filter into memory and sets it to the 
keyboard. 
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SETCOM 



Advanced Programmer’s Command 

SETCOM [(parameters)] 



Adjusts the parameter values of the RS-232C driver program 
COM/DVR. Before you can use SETCOM, you have to install the 
driver using the SET command (see Appendix I). 

You can use SETCOM to adjust your computer so that it can 
communicate with another computer or a piece of computer 
equipment. 

The RS-232C port lets you communicate with: 

• another computer 

% 

• a modem 

• a serial printer 

The parameters configure the RS-232C port, and establish line 
conditions. 

The parameters are: 

DEFAULT returns all parameters to their start-up values. 

BAUD =number sets the BAUD rate to any supportable rate. 
number can be 110, 135, 150, 3001 600, 1200, 2400, 4800, 
9600. The default value for BAUD is 300. 

WORD= number sets the word length to number, number can 
be 5, 6, 7, or 8. The default value for number is 7. 

STOP =number sets the number of stop bits per word. 

number is either 1 or 2. The default value for number is 1. 
PARITY =switch sets the parity switch to either YES or NO. If 
you specify YES, you can also use EVEN or ODD. The 
default values for PARITY are YES and EVEN. 

QUERY prompts you for each parameter. 

BREAK = value sets the logical BREAK to value. The default 
value for BREAK is hexadecimal 03 ( (CONTRODflTI ). 

EVEN sets parity to even, if parity switch is YES. 

ODD sets parity to odd, if parity switch is YES. 

BREAK cannot be abbreviated. 

Examples 

SETCOM (ENTER) 

displays the current configuration of the RS-232C port in the following 
format: 
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RS232 parameters: 

Baud = 300 

Word Length = 7 
Stop Bits = 1 
Parity = ON 

Even = ON 

Break value = X’03’ 

Output control line status: 

DTR = ON 
RTS = OFF 

Input control line conditions observed: 

Rl = IGNORE 
DSR = IGNORE 
CD = IGNORE 
CTS= IGNORE 

SETCOM (BAUD=300>WORD=8>STOP=1 » PARITY = NO) (ENTER) 

configures the RS-232C using the values specified. Notice that 
PARITY is specified as NO. 

Technical Information ~ 

This command allows you to set the parameters to values that match 
any other RS-232C devices. The receiving side of the driver is 
interrupt driven and contains an internal one-character buffer to 
prevent loss of characters during disk I/O and other lengthy 
operations. The system usually uses the *CL devspec to 
communicate with the RS-232C port. 

If you are using a serial printer, (1) use SET to set *CL to COM/DVR 
(see Appendix I), (2) use SETCOM to set the proper parameters, and 
(3) use the command: 

ROUTE *PR TO *CL (ENTER) 

to direct output to the RS-232C (rather than the standard parallel 
port). Radio Shack printers do not require this procedure since they 
use the parallel printer port. 

The line condition parameters let you set up the conventions required 
by most communicating devices. 

The RS-232C line output parameters are: 

DTR = switch Data Terminal Ready 
RTS=switch Request To Send 

The RS-232C line input parameters are: 
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DSR =switch Data Set Ready 
CD = switch Carrier Detect 
CTS =switch Clear To Send 
R\-switch Ring Indicator 

switch is either YES or NO. You cannot abbreviate any of the 
RS-232C line parameters. 

As specified by standard RS-232C conventions, a TRUE condition 
means a logical 0, or positive voltage. A FALSE condition means a 
logical 1, or negative voltage. 

DTR and RTS can be set to a constant TRUE by specifying the YES 
switch. If DSR, CD, CTS, or Rl is specified YES, the driver observes 
that signal and waits for a TRUE condition before sending each 
character. If specified NO, the driver waits for a false condition before 
sending a character. If not specified, that signal is ignored. 

The BREAK parameter allows you to set a logical BREAK character. 

This is useful in “host” type applications. The BREAK parameter 
causes the serial driver to set the system break bit whenever a 
modem break (extended null) or an ASCII logical BREAK is received. 
The system pause bit is set whenever the hex code 60 is received. 
The system enter bit is set whenever a carriage return (0D) is 
received. 

The default for BREAK is 3, so a (CONTROD fCl sets the break bit. Use 
BREAK =value to to set another character as the logical break. 

Technical Examples 

SETCOM (BREAK) (ENTER) 

configures the RS-232C port to the default values. Specifying BREAK 
with no value assigns the default value of 3 as the logical break 
value. 

SETCOM (CTS) fENTER) 

configures the RS-232C port to the default values. Because CTS is 
specified, the driver looks at the CTS line for a TRUE condition before 
it sends a character. 

Sample Use 

Suppose you want to log-on to CompuServe. First, you have to SET 
*CL to COM/DVR, and then you have to use SETCOM to set the 
parameters of the RS-232C port so that your Model 4 can 
communicate with CompuServe. See the Logging-On to CompuServe 
section in Appendix A. 


J 
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SETKI 



Advanced Programmer’s Command 

SETKI [(parameter)] 


Sets keyboard repeat parameters. If you do not specify a parameter, 
the current delay and repeat rate settings are displayed. 

You can use SETKI to adjust how your keyboard reacts when you 
press a key. 

The parameters are: 

DEFAULT returns the parameters to their start-up values 

RATE =number sets the repeat rate as number, number is any 
number greater than or equal to 1. number defaults to 2. 

WAIT= number sets the initial delay between the time a key is 
first pressed and the first repeat of that key as number, 
number is any number greater than or equal to 10 . number 
defaults to 22. 

QUERY prompts you to enter new values for RATE= number 
and WAIT= number. 

Examples 

SETKI (RATE) (ENTER) 
sets the repeat rate to the default value of 2. 

SETKI (WAIT=15) (ENTER) 
sets the delay rate to 15. 

SETKI (ENTER) 

displays the current delay and repeat rate settings in the format: 

Wait = 15, Rate=2 
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SPOOL 



Command 

SPOOL [devspec] [TO] [filespec] (parameters) 




establishes a First-In, First-Out buffer for a specified device (usually a 
line printer). 

You can use SPOOL to print data while you perform other operations 
on your computer (such as create a BASIC program). 

If you do not specify devspec, it defaults to *PR. 

The parameters are: 

NO turns off the spooler and resets devspec. 

MEM = number specifies number as the amount of memory 

buffer (in K) to be used by the spooler. The value of number 
is 1 - 32. 

BANK = number selects one of three 32K banks of memory to be 
used as the spool buffer, number can be a 0, 1, or 2. The 
default value of number is 0. 

DISK = number specifies number as the amount of disk space (in 
K) to be used by the spooler. The value of number cannot 
be larger than the amount of available space (in K) on the 
disk. 

PAUSE temporarily suspends output to devspec. 

RESUME restarts devspec after a PAUSE. 

CLEAR clears the spool buffer. 

How Data Is Spooled To a Device 

All data sent to devspec, such as a printer, is placed in an output 
buffer where it waits until the device is again available to accept the 
data. 

There are two kinds of output buffers: memory and disk. You can set 
up a spooler with both types of buffers. Or, you can set up a spooler 
with a memory buffer only. 

The minimum space allocation for the memory buffer depends on 
which BANK you select. If you specify BANK 0, a minimum of IK 
(1024 bytes) is allocated for the memory buffer. If you specify BANK 
= 1 or BANK = 2, the entire 32K bank is automatically used for the 
memory buffer. 

If you specify both buffers, data is sent first to the memory buffer. 
When the memory buffer is full, the data is sent to a disk buffer 
named filespec, where it waits to be sent to the device. If you specify 
a memory buffer only, data is sent to a memory buffer until the device 
is ready to accept it. 
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When you specify filespec, you may also use the DISK parameter to 
specify the amount of disk space to be used by the spooler. TRSDOS 
creates a file of the size specified. If you do not specify DISK =, 
approximately 5K of disk space is automatically allocated to filespec. 

To prevent TRSDOS from allocating any disk space to SPOOL, 
specify DISK = 0. 

filespec remains open as long as SPOOL is on. Do not REMOVE this 
file or remove the disk from the drive without closing the file (by 
issuing a SPOOL devspec (NO) command). 

You cannot issue a SYSGEN library command if the spooler is on. 

Once the spooler is turned off, you can turn it on again. The same 
memory locations are used, but the following restrictions apply: 

• The original parameters are not affected by turning devspec 
off and then on. 

• Any parameter specified the second time cannot exceed the 
memory or disk parameters originally given. If they do, an 
error occurs. 

Examples 

SPOOL *PR TO TEXTFILE : 0 ( MEM = 5 *DISK = 15) (ENTER) ~ 

allocates 5K of memory and 15K of disk space in a file named 
TEXTFILE/SPL on Drive 0. Since you did not specify an extension to 
TEXTFILE, it defaulted to /SPL. 

Any output for the printer is buffered and sent to the line printer (*PR) 
as fast as the printer can accept the characters. If the 5K memory 
buffer is filled, the data is written to the disk file TEXTFILE/SPL on 
Drive 0. 

SPOOL *PR ( BANK = 1 >D I SK = 0 ) (ENTER) 

creates a 32K memory buffer for data sent to *PR. Any output for the 
printer is sent to the memory buffer and then spooled to *PR when it 
is available to accept the data. Since the parameter DISK = is 
specified without any size, none of the spooled data is sent to a disk 
file. 

If the memory buffer is filled, TRSDOS does not process any more 
printer data until *PR has printed enough data to bring the number of 
characters waiting to be printed below 32K (the size of the memory 
buffer). 

SPOOL (CLEAR) (ENTER) 
clears the information in the spool buffer. 

SPOOL *PR (NO) (ENTER) 

rs 
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turns off the spooler and closes the associated disk file. Any filtering, 
linking, setting, or routing done to *PR is reset. 

You cannot close the disk file by issuing a RESET or REMOVE library 
command. SPOOL must be turned off to close the file. 

Sample Use 

Since most programs produce reports faster than the printer can print 
the data, you can use SPOOL to let the programs run at top speed 
without having to stop and wait on the printer. That is, while the first 
program’s report is still printing, you can begin executing the second 
program. 
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Advanced Programmer’s Command 
SYSGEN [(switch)] [(DRIVE = drive)] 


creates a configuration file on drive to store information about your 
system. 

You can use SYSGEN to create a file of current device and driver 
configurations that you want TRSDOS to execute each time you 
return your computer to the TRSDOS copyright and start-up message. 

If you do not specify drive, it defaults to Drive 0. 

The switch is either YES or NO. 

If you specify switch as YES, then your system creates a 
configuration file. If you don’t specify switch, then YES is assumed. 

If you specify switch as NO, then your system removes the 
configuration file. However, your system’s current configuration does 
not change until you reset your computer. 

When you issue a SYSGEN command, all current device and driver 
configurations are stored in a file named CONFIG/SYS. The file is 
invisible in the directory. 

Each time you reset your computer, the configuration stored in this file 
is loaded into memory. If you don’t want this configuration loaded into 
memory, hold down the (CLEAR) key when you reset the system (see 
the BOOT command). 

When you start up or reset your computer, it is configured before any 
AUTO command executes. 

The configuration file CONFIG/SYS contains: 

• All active background tasks (such as CLOCK, DEBUG, 

TRACE, etc.). 

• All filtering, linking, routing, and device setting (including 
RS-232C and Kl settings). 

• All programs that were loaded into high memory above 
HIGH$. All memory from HIGH$ to the top of memory is 
written to CONFIG/SYS. HIGH$ can be set with the MEMORY 
command or with the @HIGH$ supervisor call (see the 
Technical Reference Manual). 

• The present state of the VERIFY library command (YES or 
NO). 

• All Device Control Blocks (see the Technical Reference 
Manual for more information). 
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• The present state of the CAPS lock for the keyboard. 

Any ROUTE or SET involving a file should never be SYSGENed. 
SYSGENing open files can result in lost data if the disks are switched 
in the drives without the files being closed. Switching a disk with open 
files can also cause existing data to be overwritten. 

Examples 

SYSGEN (YES) fENTER) 

creates a configuration file on Drive 0 and writes the system 
configuration to it. 

SYSGEN (NO) [ENTER) 

removes the configuration file from Drive 0. 

Sample Use 

Suppose you want to create a file of commands that automatically 
execute each time you startup TRSDOS. 

Issue the commands: 

TIME ( CLQCK=YES) [ENTER) 

SYSTEM ( TRACE=YES ) (ENTER) 

SYSGEN (YES) (ENTER) 

to create a CONFIG/SYS file that contains CLOCK and TRACE 
information. 
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SYSTEM 



Advanced Programmer’s Command 

SYSTEM {parameters) 


configures certain areas of your TRSDOS system. 

You can use SYSTEM to determine some of the commands that are 
put in the file that SYSGEN creates. 

You can see the current configuration of your TRSDOS system by 
issuing a DEVICE or a MEMORY command. 

Using the SYSTEM command, you can set or change the disk drive 
configuration and turn on or off different keyboard, video, and 
hardware drivers. 


When you configure your system, you can store the configuration on 
the disk in Drive 0 with the SYSGEN library command. 

Certain SYSTEM commands load driver routines into high memory. 
Be aware that your overall free memory decreases accordingly when 
you use driver routines. 

SYSTEM Commands 


SYSTEM (ALIUEC = swi tc/?3 ) 


IBM 


displays an “alive” character in the upper right corner of the screen. 

If the alive bug is moving, the task processor is running. Note that the 
alive bug may continue moving (indicating an alive system) even 
when the SYSTEM (TRACE) library command display has stopped. 

If the alive bug is not moving, then the system is “hung up.” Also, the 
bug stops during FORMAT operations and disk I/O. 


The switch is either YES or NO. If you do not specify switch, YES is 
assumed. The ALIVE parameter uses some RAM in high memory. 


SYSTEM (BLINK = swi tch) (ENTER) 
SYSTEM (BLINK = numbe r) (ENTER) 
SYSTEM (BLINK tparameter) (ENTER) 


controls the TRSDOS cursor character. 


switch is either YES or NO. Specifying YES turns the blinking cursor 
ON. Specifying NO turns the blinking of the cursor OFF. 

number is an ASCII value in decimal. For example, if yoU specify 
SYSTEM (BLINK=42), the blinking cursor character is an asterisk 
(character 42). 

The parameters are: 

LARGE turns on a large blinking cursor. 

SMALL turns on a small blinking cursor. 
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Specifying SYSTEM (BLINK) returns the cursor to its start-up 
character and size. 

SYSTEM ( BREAK E = sui tchl ) (ENTER) 
enables or disables the (BREAK) key. 

The switch is either YES or NO. If you do not specify switch, YES is 
assumed. 

Once the (BREAK) key is disabled by issuing a SYSTEM (BREAK = NO) 
COMMAND, pressing it has no effect. 

You can re-enable it at any time by issuing a SYSTEM 
(BREAK = YES) command. This command also enables the (BREAK) 
key if it was disabled by the AUTO library command. 

If you switch Drive 0 disks or change the logical Drive 0 with the 
SYSTEM (SYSTEM) command, the default value you select for 
BSTEP is taken off the new Drive 0 disk. 

SYSTEM (DftTE[ = s witchl ) (ENTER) 

enables or disables the prompt for the date when you power up your 
system. 

The switch is either YES or NO. 

If you specify the switch as YES, the system enables the date prompt 
if it has been disabled with the NO switch. If you do not specify 
switch, YES is assumed. 

If you specify the switch as NO, the date prompt is disabled when 
you power up or restart your system. 

Since the date is used extensively throughout the TRSDOS system, 
we recommend that you never disable the initial date prompt. 

Z- _ 

SYSTEM ( DRI UE = dri ve »[ pa rame t e rs 2 ) (ENTER) 

sets certain parameters for the disk drives in your system. 

drive is any valid drive number in your system. 

The parameters are: 

CYL =number sets the default number of cylinders that is used 
with the FORMAT utility, number is in the range of 35 to 96. 
DELAY = NO/YES sets the DELAY time for floppy disks. DELAY 
time is the time allowed between the drive motor start-up 
and the first attempted read of the diskette in that drive. If 
you specify DELAY = NO, the DELAY time is set to .5 
seconds (the standard DELAY time). If you specify 
DELAY=YES, the DELAY time is set to 1 second. 

DISABLE removes access to the specified drive. 

ENABLE allows access to a drive that has been disabled. 
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Error Conditions 

CYL is written to the system information sector on Drive 0. If you 
switch the disk in Drive 0, these values are taken from the new disk in 
Drive 0 if you format a disk. 

If you try to access a disk after you have DISABLEd it, the error 
“Illegal drive number” appears. 

If you ENABLE a drive that is not available on your system or that is 
not set up with the SYSTEM (DRIVE = .DRIVER) command, 
unpredictable results follow. 

SYSTEM (DRIUE = </ri ve >DRIUER=" fi lespec" ) (ENTER) 

To access the disk drives, TRSDOS uses information stored in 
memory in the Drive Code Table (DCT). Since these drives are preset 
in your system, no special configuration should have to be done. This 
command is used for Radio Shack hard disk installation. 

SYSTEM (DRIUE = </rivf>WPC = switc/i] ) (ENTER) 

sets the software Write Protect status for the disk in drive. 

The switch is either YES or NO. If you do not specify either one, YES 
is assumed. 

If you specify WP = YES, you cannot write to the disk, although you 
can still read from it. If you specify WP = NO, you can write to and 
read from the disk (assuming the disk is not hardware write 
protected). 

If you do not specify drive, the switch that you specify applies to all 
drives enabled in your system. 

If there is a write-protect tab on a disk, specifying WP = NO does not 
allow you to write to the disk. 

SYSTEM (RESTORE l^switchl) (ENTER) 

determines whether all drives are to be restored when the system is 
reset. Drives are restored by moving the drive heads to track 0. 

If you specify RESTORE = YES, the drives are restored on reset. If 
you do not specify switch, YES is assumed. If you specify 
RESTORE = NO, the drives are not restored on reset. 

SYSTEM (SYSRES = nu/»f>er) (ENTER) 

adds TRSDOS system “overlays” into high memory. You can load 
SYS files 1, 2, 3, 4, 5, 9, 10, 11, and 12 with this command. 

Adding certain of these SYS overlays to memory speeds up most disk 
I/O, because these overlays do not have to be loaded from disk every 
time they are needed. This also allows you to purge these overlays 
from your system disk using the PURGE library command, providing 
more room for data and programs. 
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SYS0 and SYS2 must remain‘on any booting disk if a configuration 
file created with the SYSGEN library command is loaded. 

To see which overlays are currently resident in high memory, issue a 
DEVICE library command. 

You can add only one system overlay to high memory in a command 
line. 


SYSTEM (SYSTEM = drive) (ENTER) 

assigns a drive other than Drive 0 as your system drive. 

drive is any drive currently enabled in your system. There must be a 
system disk in drive when you issue the command. If drive is not 
ready, the message “Insert SYSTEM diskette in drive x! ” appe ars. 
Insert a system diskette in the indicated drive, or press (BREAK) to 
abort the command and return to TRSDOS Ready. 

Every time you issue this command, the logical drive numbers of the 
drives change. You can repeat this command as many times as you 
wish, but be careful not to lose track of which drive is assigned to 
which logical drive number. 

SYSTEM (TIMEC = switchJ) (ENTER) 

turns on or off the start-up time prompt. 

The switch is either YES or NO. 

If you specify TIME = YES, you enable the start-up time prompt. If you 
do not specify switch, YES is assumed. If you specify TIME = NO, you 
disable the start-up time prompt. 

When you issue this command, you must not have a write-protected 
disk in Drive 0. 

SYSTEM (TRftCE[ = sm' tchl) (ENTER) 

displays the contents of the Program Counter (PC) in the upper right 
corner of the video display. The display is a hexadecimal address and 
is constantly updated as a “low priority background task” (see the 
explanation of the @ADTSK supervisor call in the Technical 
Reference Manual). 

The switch is either YES or NO. 

Use the TRACE command to help you debug assembly language 
programs. 

SYSTEM ( TYPEC = swi tchl ) (ENTER) 

turns on or off the task processing of the keyboard type-ahead 
feature. Type-ahead is active when you startup your computer. 

The switch is either YES or NO. 

You can restart the type-ahead task processing with the SYSTEM 
(TYPE = YES) command. 
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TAPE100 filel [TO] file2 (parameters) 


Utility 


Lets TRSDOS (1) read a cassette tape file and write it to a disk file, 
or (2) read a disk file and write it to a cassette tape. 

You can use TAPE100 to read files from cassette tape as well as 
from Model 4 disks. 

The cassette tape must have been made with the Model 100 
computer. 

filel is either a TRSDOS filespec or a Model 100 filename. 
file2 is either a TRSDOS filespec or a Model 100 filename. 

A Model 100 filename is 1 - 6 characters long and it must begin with 
a letter. For example, ACCT61, LETTER, and ABFILE can be Model 
100 filenames. 

The parameters are: 

READ specifies that you want to read a file (filel) from tape and 
write it to a file ( file2 ) on disk. If you specify READ, you do 
not have to specify filel. TRSDOS simply reads the first text 
file it sees on the tape. 

WRITE specifies that you want to read a disk file (filel) and write 
it to a tape as file2. 

Examples 

TAPE100 PRNTER TO PRINT/DAT:0 (READ) i ENTER) 

TRSDOS reads the Model 100 file PRNTER and writes it to the disk 
in Drive 0 as PRINT/DAT. 

TAPE100 ACCTING/TXT: 1 (READ) (ENTER) 

TRSDOS reads the first text file it finds on a Model 100 tape and 
writes it to the disk in Drive 1 as ACCTING/TXT. 

TAPE100 WEST/DAT: 0 TO WESTRN (WRITE) (ENTER) 

TRSDOS reads the Drive 0 disk file WEST/DAT and writes it to a file 
on a Model 100 tape named WESTRN. 

Error Conditions 

Any file (disk or tape) must fit in available memory or the error 
message “File too large to fit in available memory” appears. 



T 
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TIME 



TIME [ hh:mm:ss] [(parameter)] 


Command 


You can use TIME to see the current time. You can also use it to 
reset the time. 

If you specify hh\mm:ss, TRSDOS resets the time. If you do not 
specify it, TRSDOS displays the current time. 

The parameter is: 

CLOCK = YES/NO turns the clock display on or off. YES is the 
default. 


The real time clock turns off while TRSDOS does some of its disk I/O 
functions, such as BACKUP and FORMAT, so do not depend on the 
clock for constantly accurate time and date information. 

You can enable and disable the prompt for time on power-up or reset 
with the SYSTEM (TIME = ) command. 

Examples 

TIME (INTER) 

displays the real time of the system. The clock is reset to 00:00:00 
every time you power up. 

TIME ( CLOCK = YES) (ENTER) 


displays the real time clock in the upper right corner of the screen. 
Note: CLOCK will print over whatever TRSDOS attempts to print at 
the location occupied by the clock display. 

TIME 12 i 29: 34 (ENTER) 


sets the clock to 12:29:34 p.m. The latest acceptable time is 23:59:59, 
as the clock runs in the 24-hour mode. When the clock reaches 
23:59:59, the date is automatically updated. 


The time lag between pressing (ENTER) and the time set on the clock 
is approximately 2 seconds. So, when setting the clock with the 
correct time, remember to adjust for the 2-second time lag. 
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VERIFY 


VERIFY [(switch)] 


Command 


Controls the verify function. 

You can use VERIFY to assure you that data was properly written to 
a disk. 

When VERIFY is on, TRSDOS reads the data it writes to the disk to 
verify that the data is readable. 

The switch is either ON or OFF. 

A TRSDOS floppy disk system starts up with VERIFY off. A hard disk 
system starts up with VERIFY on. 

Although having the VERIFY switch turned on provides a reliability 
check during disk I/O, it also increases overall processing time when 
you write to a disk file. You must determine if the increase in reliability 
warrants the increase in processing time. 

All disk writes are automatically verified during any BACKUP utility 
function, whether or not the VERIFY switch is on. 

The state of the VERIFY command can be saved in the configuration 
file with the SYSGEN library command. (You can check the present 
status of VERIFY using the DEVICE command.) 

Examples 

VERIFY (ON) (ENTER) 
turns on the verify function. 

VERIFY (OFF) (ENTER) 
turns off the verify function. 

VERIFY (ENTER) 
turns on the verify function. 

Sample Use 

Suppose you are writing a tax file named TAX/TXT to disk and it is 
extremely important that the information in the file be correct. 

Using VERIFY causes TRSDOS to produce an informative message 
when data written to TAX/TXT is written incorrectly. An informative 
message could indicate that the disk needs to be replaced or the 
drives need to be cleaned. 
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Part II/ BASIC For TRSDOS Version 6 Reference 
Manual 



BASIC 





Introduction 



This part of the manual is about the BASIC language. BASIC for 
TRSDOS Version 6 is an “interpreter.” When you run a program, it 
executes each statement one at a time. This makes it quick and easy 
to use. It also allows you to take advantage of many of TRSDOS 
Version 6’s features, such as: 

• Faster running programs 

• Better graphics capabilities 

• More print positions on the screen 



About this Manual 

This is a reference manual, not a tutorial. We assume you already 
know BASIC and are using this manual to quickly find the information 
you need. 

Section III — Operations. This section shows how to load BASIC. 
It also demonstrates how to write, run and save a BASIC 
program on disk. 

Section IV — The BASIC Language. This section includes a 
definition for each of BASIC’s keywords (statements and 
functions) in alphabetical order. In addition, it shows how to write 
a program to store data on disk. 

IMPORTANT NOTE: If you have read “Getting*Started with TRS-80 
BASIC”, you need to know the differences between TRSDOS Version 
1 and TRSDOS Version 6 BASIC. Appendix E shows these 
differences. You also need to know how to use “disk files.” This is 
explained in Chapter 5. 


Notations 

CAPITALS 

italics 

... (ellipsis) 
X’NNNN 
O’NNNN 
(KEYNAME) 

b 

1 / 


material which must be entered exactly as it 
appears. 

words, letters, characters or values you must 
supply from a set of acceptable entries. 

items preceding the ellipsis may be repeated. 

NNNN is a hexadecimal number. 

NNNN is an octal number. 

one of the keys from your keyboard. 

a blank space character (ASCII code 32). For 
example, in 

BASICbbPROG 

there are two spaces between BASIC and PROG. 
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Terms 




buffer 


[parameters] 


[arguments] 


syntax 


a number between 1 and 15. This refers to an 
area in memory that BASIC uses to create and 
access a disk file. Once you use a buffer to create 
a file, you cannot use it to create or access any 
other files; you must first close the file. You may 
only access an open file with the buffer used to 
open it. 

information you supply to specify how a command 
is to operate. Parameters enclosed in brackets are 
optional. 

expressions you supply for a function to evaluate. 
Arguments enclosed in brackets are optional. 

a command with its parameter(s), or a function 
with its argument(s). This shows the format to use 
for entering a keyword in a program line. 


Terms Used in Chapter 7 for Brevity: 

line a numeric expression that identifies a BASIC 

program line. Each line has a number between 0 
and 65529. 

integer any integer expression. It may consist of an 

integer, or several integers joined by operators. 
Integers are whole numbers between -32768 and 
32767. 


string any string expression. It may consist of a string, or 

several strings joined by operators. A string is a 
sequence of characters which is to be taken 
verbatim. 


number 


dummy number 
or dummy string 


any numeric expression. It may consist of a 
number, or several numbers joined by operators. 

a number (or string) used in an expression to 
meet syntactic requirements, but whose value is 
insignificant. 


Part II is organized this way: 

Section III. Operations 

Chapter 1. Sample Session 

Chapter 2. Command Mode 

Execution Mode 




o 
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Chapter 3. Line Edit Mode 

Section IV. The BASIC Language 
Chapter 4. BASIC Concepts 

Chapter 5. Disk Files 

Chapter 6. Introduction to BASIC Statements and Functions 

Chapter 7. BASIC Statements and Functions 
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Section III/ Operations 








Chapter 1/ Sample Session 


The easiest way to learn how BASIC operates is to write and run a 
program. This chapter provides sample statements and instructions to 
help familiarize you with the way BASIC works. 

The main steps in running a program are: 

A) Loading BASIC 

B) Typing the program 

C) Editing the program 

D) Running the program 

E) Saving the program on disk 

F) Loading the program back into memory 


Loading BASIC 

After you power up your system and install the diskette, the TRSDOS 
Version 6 start-up logo is displayed. Then, the following prompt 
appears: Date? 

To answer this prompt, type today’s date in this format: DD/MM/YY; 
then press (ENTER) . For example, for December 1, 1983, type: 

12/01/83 (ENTER) 

The computer converts these numbers to: Thu, Dec 1, 1983 and 
displays the message “TRSDOS Ready”. This indicates that you are 
at the Operating System level. To load BASIC into the system, type: 

BASIC (ENTER) 

A paragraph with copyright information appears on your screen, 
followed by: Ready 

You may now begin using BASIC. 


Options for Loading BASIC 

When loading BASIC, you can also specify a set of options. They are: 

BASIC [program] ([F = number of files] [,M = highest memory 
location]) 

Program specifies a program to run immediately after BASIC is 
started. 

F- specifies the maximum number of data files that may be open at 
any one time (from 0-15). If you omit this option, the number of files 
defaults to three. Each file you specify uses 564 bytes of memory. 

M= specifies the highest memory location for BASIC to use. Omit 
this option unless you are going to call assembly-language 
subroutines. (In that case, you may want to set the amount of 
memory well below the high-memory modules of TRSDOS.) If you 
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omit this option, the system allocates all memory up to the HIGH$ 
marker to BASIC. HIGHS can be adjusted through the MEMORY 
library command. See the TRSDOS Reference Manual for more 
details. 

Examples 

TRSDOS Ready 

BASIC PAYROLL (F = 5> (ENTER) 

initializes BASIC, then loads and runs the program PAYROLL; allows 
five data files to be open; uses all memory available. 

TRSDOS Ready 

BASIC ( M=4505G ) (ENTER) 

initializes BASIC; allows three data files to be open; sets the highest 
memory location to be used by BASIC at 45056. 

TRSDOS Ready 

BASIC (M=327GB » F = 6) (ENTER) 

initializes BASIC; sets the highest memory location at 32768; allows 
six data files to be open. Notice that the sequence in which the M = 
and F = options are specified is irrelevant. 

TRSDOS Ready 
BASIC 

initializes BASIC; allows three data files to be open; uses all memory 
available. 



Typing the Program 

Let’s write a small BASIC program. Before pressing (ENTER) after each 
line, check the spelling. If you have made any mistakes, use the © 
key to correct them. 

10 A$="WILLI AM SHAKESPEARE WROTE" (ENTER) 

15 B$= "THE MERCHANT OF VENICE" (ENTER) 

20 PRINT A$ 5 B$ (ENTER) 

Check your spelling again. If it is still not perfect, enter the line 
number where you made the mistake. Then type the entire line again. 

For example, suppose you had typed: 

15 B$="THE MERCHANT OF VENICE" 

To correct line 15, re-type it: 

15 B$= "THE MERCHANT OF VENICE" (ENTER) 

Then type: 

RUN (ENTER) 
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Your screen should display: 

WILLIAM SHAKESPEARE WROTE THE MERCHANT OF 
VENICE 

BASIC replaced line 15 in the original program with the most recent 
line 15. 


NOTE: BASIC “reads” your program lines in numerical order. It 
doesn’t matter if you entered line 15 after line 20; it will still read and 
execute 15 before “looking” at 20. 

BASIC has a powerful set of commands which allow you to correct 
mistakes without having to re-type the entire line. These commands 
are discussed in Chapter 3, the “Line Edit Mode.” 


Saving the Program on Disk 

You can save any of your BASIC programs on disk. To do this, you 
assign it a “filespec”. 

For example, if you wanted to save the program we just wrote, you 
could assign it the filespec “AUTHOR”. Type the following command: 

SAVE "AUTHOR" (ENTER) 

It takes a few seconds for the computer to find'a place on disk to 
store our program. When this process is completed, it displays Ready. 
The program is now saved on disk. 

IMPORTANT NOTE: A filespec can have a maximum of eight 
alphanumeric characters. It can also have an optional extension, up to 
three characters long. A slash / must be included between the 
filespec and the extension. The first character of both the filespec and 
the extension must be a letter. 

Example 

SAVE "AUTHOR/WIL" (ENTER) 

You may also add a drive number to your filespec by typing a colon : 
and the drive number. 


Example 

SAVE "AUTHOR; 1" (ENTER) 


tells the computer to save “AUTHOR” on the disk in Drive 1. 
Otherwise, the computer assumes you to save it on the first available 
drive. If you do specify a disk drive, make sure you have a disk in that 
drive. 


2-11 












Loading the Program 

If, after writing or running other programs, you wanted to go back and 
use this program again, you must “load” it back into memory. To do 
this, type: LOAD “filespec”, R 

Example 

LOAD "AUTHOR". R (ENTER) 

tells the computer to load the program “AUTHOR” from disk into 
memory: option R tells the computer to run it. 

Another way to load and run a program is to type: RUN “filespec”. 
RUN automatically loads and runs the program specified by 
“filespec”. 

The SAVE, LOAD and RUN commands are discussed in more detail 
in Chapter 7. 
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Chapter 2/ 

Command And Execution Modes 


This chapter describes BASIC’s command and execution modes. The 
command mode is for typing in program lines and immediate lines. 
The execution mode is for executing programs and immediate lines. 



Command Mode 

Whenever you enter the command mode, BASIC displays the prompt: 
Ready 

In the command mode, BASIC does not‘‘re ad’’ your input until you 
complete a “logical line” by pressing (ENTER) . This is called “line 
input”, as opposed to “character input”. 

A logical line is a string of up to 255 characters and is always 
terminated by pressing (ENTER) . Of these 255 characters, 249 are 
reserved for the line itself; the other six are reserved for the line 
number and the space following the line number. 

A physical line, on the other hand, is one line on the display. It 
contains a maximum of 80 characters. 

For example, if you type 100 R’s and then press (ENTER) , you have 
two physical lines, but only one logical line. 

Interpretation of a Line 

BASIC always ignores leading spaces in the line — it jumps ahead to 
the first non-space character. If this character is not a digit, BASIC 
treats the line as an immediate line. If it is a digit, BASIC treats the 
line as a program line. 

For example, if you type: 

PRINT "THE TIME IS" TIME$ (ENTER) 

BASIC takes this as an immediate line. 

But if you type: 

10 PRINT "THE TIME IS" TIME$ (ENTER) 

BASIC takes this as a program line. 


Immediate Lines 

An immediate line consists of one or more statements separated by 
colons. The line is executed as soon as you press (ENTER) . For 
example: 

Ready 

CLS: PRINT "THE SQUARE ROOT OF 2 IS" SQR<2) 
is an immediate line. When you press (ENTER) . BASIC executes it. 
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Program Lines 

A program line consists of a line number in the range 0 to 65529, 
followed by one or more statements separated by colons. When you 
press (ENTER) , the line is stored in memory, along with any other lines 
you have entered this way. The program is not executed until you 
type RUN or another execute command. For example: 

100 CLS: PRINT "THE SQUARE ROOT OF 2 IS" 

SQR(2) 

is a program line. When you press (ENTER) . BASIC stores it in 
memory. To execute it, type: 

RUN (ENTER) 

NOTE: If you include numer ic cons tants in a line, BASIC evaluates 
them as soon as you press (ENTER) : it does not wait until you RUN the 
program. If any numbers are out of range for their ty pe, BAS IC 
returns an error message immediately after pressing (ENTER) . 


Special Keys in the Command Mode 


© 

or (CTRLi m 


(SPACE BAR) 


(BREAK) 


(CTRDQD 

or® 

(EffiD 


(ENTER) 


(SHIFT) 

© 


Backspaces the cursor, erasing the preceding 
character in the line. Use this to correct typing 
errors before pressing (ENTER) . 

Enters a blank space character and advances the 
cursor. 

Interrupts line entry and starts over with a new 
line. 

Line feed — starts a new physical line without 
ending the current logical line. 

Switches the display to either all uppercase or 
uppercase/lowercase mode. 

Ends the current logical line. BASIC “takes” the 
line. 

Deletes the current line. 


Execution Mode 


When BASIC is executing statements (immediate lines or programs), 
it is in the execution mode. In this mode, the contents of the video 
display are under program control. 


Special Keys in the Execution Mode 

(SHIFT) f^) Pauses execution. Press any other key (except 

(BREAK) to continue. 
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(BREAK) Terminates execution and returns you to command 

mode. 

(ENTER) interprets data entered from the keyboard as a 

response to the INPUT statement. 




2-15 





























Chapter 3/ Line Edit Mode 


This mode enables you to “debug” (correct) programs quickly and 
efficiently. It allows you to correct a program line without having to 
re-type the entire line. 

If your computer encounters a syntax error while executing a 
program, it automatically puts you in the “line edit mode.” The display 
shows: 

Syntax error in line number 
Ready 

line numbe r 

(line number is the program line in which the error occurred.) In this 
case, you are ready to use the edit mode commands and 
subcommands described later in this Chapter. 

However, if you wish to activate the line editor yourself (because you 
have noticed a mistake or wish to make a change in a long program 
line), type: 

EDIT line number (ENTER) 

This lets you edit the specified line number. (If the line number you 
specify has not been used, an “Undefined line number" error occurs). 

You may also type: 

edit . (Inter) 

The period after EDIT means that you want to edit the current 
program line, the last line entered, the last line altered, or a line in 
which an error has occurred. Notice that you need to type a blank 
before the period; otherwise, BASIC gives you a “Syntax error” 
message. 

For example, type the following line and press (ENTER) . (To type the 
exponent sign ", pre ss (iLlARl fD). 

100 FDR I = 1 TO 10 STEP .5: PRINT I> I*2» 1*3: 
NEXT 

This line will be used in exercising all the edit subcommands 
described below. 

Now type EDIT 100 and press (ENTER) . The computer displays: 

100 


This starts the editor. You may now begin editing line 100. 














Special Keys in the Edit Mode 

(INTER) 


Pressing (ENTER) in the edit mode records all the changes you made in 
the current line and returns you to the command mode. 

Space bar 

Pressing the space bar moves the cursor over one space to the right 
and displays any character stored in the preceding position. For 
example, using line 100 entered above, put the computer in the edit 
mode so the display shows: 

100 

Now press the space bar. The cursor moves mover one space and 
the first character of the program line is displayed. If this character 
was a blank, then a blank is displayed. Press the space bar again 
until you reach the first non-blank character: 

100 F 

is displayed. To move over more than one space at a time, type the 
desired number of spaces first, then press the space bar. For 
example, type 6 and press the space bar. The display should show 
something like this (depending on how many blanks you inserted in 
the line): 

100 FOR I = 

Now type 8 and press the space bar. The cursor moves over eight 
spaces to the right, and eight more characters are displayed. 

100 for i = 1 TO 10 

L (List Line) 

displays the remainder of the program line (unless the computer is 
under one of the insert subcommands listed below). The cursor drops 
down to the next line of the display, reprints the current line number, 
and moves to the first position of the line. 

For example, when the display shows 

100 

press L (without pressing (ENTER) ). Line 100 is displayed: 

100 FOR I = 1 TO 10 STEP .5: PRINT I*’ 1*2* 1*3: 
NEXT 100 

This lets you look at the line in its current form while you’re doing the 
editing. 









Insert Subcommand Mode 

The insert subcommand mode allows you to add material to a line 
while editing it. The three keys you can use to enter this subcommand 
mode are X, I and H. 

X (Extend Line) 

Displays the rest of the current line. Typing QD also moves the cursor 
to the end of the line and puts the computer in the insert 
subcommand mode. This enables you to add material to the end of 
the line. 

For example, using line 100, when the display shows 
100 

press (X) (without pressing CENTS!)) and the entire line is displayed; 
notice that the cursor now follows the last character on the line: 

100 FOR I = 1 TO 10 STEP ,5: PRINT I, I*2» 

I A 3: NEXT 

We can now add another statement to the line, or delete material 
from the line by using the © key. For example, type 

: PRINT ,, D0NE" 

w mm 

at the end of the line. If you typed: 

LIST 100 

the display should show something like this: 

100 FOR I = 1 TO 10 STEP .5: PRINT I» I A 2> 

I A 3: NEXT: PRINT "DDNE" 

NOTE: If you want to continue editing the line, press (SHlFT) CD to get 
out of the insert subcommand mode. 

I (Insert) 

Inserts material beginning at the current cursor position on the line. 

For example, type 

EDIT 100 

fENTffi) 

then use the space bar to move over to the decimal point in line 100. 
The display shows: 

100 FOR I = 1 TO 10 STEP , 

Suppose you want t o chang e the increment from .5 to .25. Press the 
CD key (don’t press (ENTER) ). The computer lets you insert material at 
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the current position. Type 2 now, and the display shows: 
100 FOR I = 1 TO 10 STEP .2 


You have made the necessary change, so press (SHIFT)fD to escape 
from the insert subcommand. Now press CD to display the remainder 
of the line and move the cursor back to the beginning of the line: 

100 FOR I = 1 TO 10 STEP .25: PRINT I# 1*2. 

1*3: NEXT: PRINT "DONE" 

100 

NOTE: You can also exit the insert subcommand and save all 
changes by pressing (ENTER) . This returns you to command mode. 

H (Hack and Insert) 

Deletes the remainder of a line and lets you insert material at the 
current cursor position. 

For example, using line 100, enter the edit mode and space over until 
just before the PRINT “DONE” statement. Suppose you wanted to 
delete this statement and insert an END statement. The display 
shows: 


100 FOR I = 1 TO 10 STEP .25: 
1*3: NEXT: 


PRINT I » 1*2. 


Press QD, then type END and press (ENTER) . List the line: 

100 FOR I = 1 TO 10 STEP .25: PRINT I. I 
1*3: NEXT: END 

should be displayed. 


NOTE: To continue editing the line, press (SHIFT)(~D to get out of the 
insert subcommand mode. 

A (Cancel and Restart) 

Moves the cursor back to the beginning of the program line and 
cancels editing changes already made. 

For example, if you have added, deleted, or changed something in a 
line, and you wish to go back to the beginning of the line and cancel 
the changes already made: first press (SHIFT) fT) (to escape from any 
subcommand you may be executing); then press (D. The cursor 
drops down to the next line, displays the line number and moves to 
the first character position. 

E (Save Changes and Exit) 

Ends editing and saves all changes made. You must be in edit mode, 
not executing any subcommand, when you press CD to end editing. 


rs 


m 


2-20 















Q (Cancel and Exit) 

Ends editing and cancels all changes made in the current editing 
session. If you’ve decided not to change the line, type 03 to cancel 
changes and leave the edit mode. 

If a syntax error is detected during program execution, BASIC starts 
the editor. To examine variable values, you must press Q before 
typing any other command. 

nD (Delete) 

Deletes the specified number n of characters to the right of the 
cursor. The deleted characters appear enclosed in exclamation points. 


For example, using line 100, space over to just before the PRINT 
statement: 

100 FOR I = 1 TO 10 STEP .25: 

Now type 19D. This tells the computer to delete 19 characters to the 
right of the cursor. The display should show something like this: 

100 FOR I = 1 TO 10 STEP .25: \PRINT I, I*2» 


When you list the complete line, you will see that everything from the 
PRINT to the next statement has been deleted. 

nC (Change) 

Lets you change the specified number of characters beginning at the 
current cursor position. If you type C without a preceding number, the 
computer assumes you want to change one character. When you 
have entered n number of characters, the computer returns you to the 
edit mode (so you’re not in the nC subcommand). 

For example, using line 100, suppose you want to change the final 
value of the FOR NEXT loop, from “10” to “15”. In the edit mode, 
space over to just before the “0” in “10”. 

100 for i = 1 TO 1 

Now press fC~) . The computer assumes you want to change just one 
character. Press GD, then press CD- When you list the line, you will 
see that the change has been made. 

100 FOR I = 1 TO 15 STEP .25: NEXT: END 

would be the current line if you’ve followed the editing sequence in 
this chapter. 

# 
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nSc (Search) 

Searches for the nth occurrence of the character c, and moves the 
cursor to that position. If you don’t specify a value for n, the computer 
searches for the first occurrence of the specified character. If 
character c is not found, cursor goes to the end of the line. 

NOTE: The computer only searches through characters to the right of 
the cursor. 

For example, using the current form of line 100 type EDIT 100 
(ENTER) , then press (3D(X)QD. This tells the computer to search for 
the second occurrence of the colon character. The display should 
show: 

100 FOR I = 1 TO 15 STEP .25: NEXT 

You may now execute one of the subcommands beginning at the 
current cursor position. For example, suppose you want to add the 
counter variable after the NEXT statement. Type I to enter the insert 
subcommand, then type the variable name, I. That’s all you want to 
insert, so press (SHIFT)fD to escape from the insert subcommand 
mode. The next time you list the line, it should appear as: 

100 FOR I = 1 TO 15 STEP .25: NEXT I: END 

nKc (Search and "Kill") 

Deletes all characters up to the nth occurrence of character c, and 
moves the cursor to that position. 

For example, using the e--* version of line 100, suppose we 
want ed to d elete the entire *r. _<p to the END statement. Type EDIT 
100 (ENTER) , then type f2YjtTO- This tells the computer to delete all 
characters up to the 2nd occu. of the colon. 

100 \F0R I s 1 TO 15 STEF - NEXT I\ 

should be displayed. The second colon still eds to be deleted, so 
type D. The display now shows: 

100 \F0R I = 1 TO 15 STEP .25: NEXT I\\:\ 

Press (ENTER) and type LIST 100 (ENTER) 

Line 100 should look something like this: 

100 END 

n© 

Moves the cursor to the left by n spaces. If no number n is given, the 
cursor moves back one space. When the cursor backspaces, all 
characters in its path are erased from the display, but they are not 
deleted from the program. Use the space bar to advance the cursor 
forward and re-display the erased characters. 
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Section IV/ The BASIC Language 

























Chapter 4/ BASIC Concepts 



This chapter explains how to use the full power of BASIC for 
TRSDOS Version 6. This information can help programmers build 
powerful and efficient programs. If you are still something of a novice, 
you might want to skip this chapter for now, keeping in mind that the 
information is here when you need it. 

The chapter is divided into four sections: 

A. Overview — Elements of a Program. This section 
defines many of the terms we will be using in the chapter. 

B. How BASIC Handles Data. Here we discuss how BASIC 
classifies and stores data. This shows you how to get BASIC to store 
your data in its most efficient format. 

C. How BASIC Manipulates Data. This gives you an 
overview of all the different operators and functions you can use to 
manipulate and test your data. 

D. How to Construct an Expression. This topic can help 
you in constructing powerful statements instead of using many short 
ones. 


A- Overview: Elements of a Program 

This overview defines the elements of a program. 

A program is made up of “statements”; statements may have several 
“expressions.” 

We will refer to these terms during the rest of this chapter. 

Program 

A program is made up of one or more numbered lines. Each line 
contains one or more BASIC statements. BASIC allows line numbers 
from 0 to 65529 inclusive. You may include up to 255 characters per 
line, including the line number. You may also have two or more 
statements to a line, separated by colons. 

* You can type a maximum of 249 characters per line. BASIC 
reserves the remaining six characters for the line number and for the 
space following the line number. 

Here is a sample program: 
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Line 

number 


BASIC Colon between 

1st 



BASIC statement 


\ 


100 CLS:'“ r F J RINT "NORMAL MODE..." 

110 PRINT "ABCDEFGHIJKLMNOPQRSTUUWXYZ" 

120 FOR I = 1 TO 1000: NEXT I 

130 CLS: PRINT CHR$<23)» "DOUBLE-SIZE MODE..." 

140 PRINT "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

150 END 

When BASIC executes a program, it handles the statements one at a 
time, starting with the first and proceeding to the last. Some 
statements, such as GOTO, ON ... GOTO, GOSUB, change this 
sequence. 

Statements 

A statement is a complex instruction to BASIC, telling the computer to 
perform specific operations. For example: 

GOTO 100 

tells the computer to perform the operations of (1) locating line 100, 
(2) transferring control to that line and (3) executing the statement(s) 
on that line. 


END 


tells the computer to perform the operation of ending execution of the 
program. 

Many statements instruct the computer to perform operations with 
data. For example, in the statement: 

PRINT"SEPTEMBER REPORT" 

the data is SEPTEMBER REPORT. The statement instructs the 
computer to print the data inside quotes. 

Expressions 

An expression is actually a general term for data. There are four 
types of expressions: 

1. Numeric expressions, which are composed of numeric data. 

Examples: 

(1 + 5.2)/3 
D 

5*B 

3.7G82 

ABS(X) + RND(0) 

SIN<3 + E) 
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2. String expressions, which are composed of character data. 

Examples: 

A$ 

"STRING" 

"STRING" + "DATA" 

MO* + "DATA" 

MID*(A* >2 *5) + MID$("MAN" *1 >2) 

M* + A* + B* 

3. Relational expressions, which test the relationship between two 
expressions. 

Examples: 

A = 1 
A*>B* 

4. Logical expressions, which test the logical relationship between 
two expressions. 

Examples: 

A$="YES" AND B$ ="N0" 

05 OR M<B OR 0>-2 
578 AND 452 

Functions 

Functions are automatic subroutines. Most BASIC functions perform 
computations on data. Some serve a special purpose, such as 
controlling the video display or providing data on the status of the 
computer. You may use functions in the same manner that you use 
any data: as part of a statement. 

These are some of BASIC’s functions: 

INT 

ABS 

STRING* 

For example, ABS returns the absolute value of a numeric 
expression. The following example shows how this function works: 

PRINT ABS ( 7*( -5) ) (ENTER) 

35 

READY 


B- How BASIC Handles Data 



BASIC for TRSDOS Version 6 offers several different methods of 
handling your data. Using these methods properly can greatly improve 
the efficiency of your program. In this section we discuss: 
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Ways of Representing Data 
Constants 
Variables 

How BASIC Stores Data 

Numeric (integer, single precision, double precision) 

String 

How BASIC Classifies Constants 
How BASIC Classifies Variables 
How BASIC Converts Data 

Ways of Representing Data 

BASIC recognizes data in two forms: directly (as constants), or by 
reference to a memory location (as variables). 

Constants 

All data is input into a program as “constants” — values which are 
not subject to change. For example, the statement: 

PRINT "1 PLUS 1 EQUALS"5 2 

contains one string constant (1 PLUS 1 EQUALS), and one numeric 
constant (2). 

In these examples, the constants “input” to the PRINT statement. 

They tell PRINT what data to print on the display. 

These are more examples of constants: 

3.14159 “L.O.SMITH” 

1.775E + 3 “0123456789ABCDEF” 

“NAME TITLE” -123.45E - 8 

57 “AGE” 

Variables 

A variable is a place in memory where data is stored. Unlike a 
constant, a variable’s value can change. This allows you to write 
programs dealing with changing quantities. For example, in the 
statement: 

A$ = "OCCUPATION" 

The variable A$ now contains the data OCCUPATION. However, if 
this statement appeared later in the program: 

A$ = "FINANCE" 

The variable A$ would no longer contain OCCUPATION. It would now 
contain the data FINANCE. 

Variables can also store numeric values. For example: 

A = 134 f 1 
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Variable Names 





In BASIC, variables are represented by names. Variable names must 
begin with a letter, A through Z. This letter may be followed by one or 
more characters (digits or letters). 

For example: 

AM A A1 BALANCE EMPLOYEE2 
are all valid and distinct variable names. 

Variable names may be up to 40 characters long. All characters are 
significant in BASIC. 

Reserved Words 

Certain combinations of letters are reserved as BASIC keywords and 
operator names. These combinations cannot be used as variable 
names. For example: 

OR LEN OPTION 

cannot be used as variable names. However, they may be embedded 
in a variable name. For example, OPTIONS is a valid variable name. 

TRSDOS Version 6 requires that all reserved words be delimited. This 
means that you must leave a blank space between a reserved word 
and any variables, constants or other reserved words. See Appendix 
F for a list of BASIC’s reserved words. 

Simple and Subscripted Variables 

Variables may also be “subscripted” so that an entire list of data can 
be stored under one variable name. This method of data storage is 
called an array. For example, an array named A may contain these 
elements (subscripted variables): 

A(0) A(1) A(2) A(3) A(4) 

You may use each of these elements to store a separate data item, 
such as: 

A(0) = 5.3 
A(1) = 7.2 
A(2) = 8.3 
A(3) = 6.8 
A(4) = 3.7 

In this example, array A is a one-dimensional array, since each 
element contains only one subscript. An array may also be 
two-dimensional, with each element containing two subscripts. For 
example, a two-dimensional array named X could contain these 
elements: 
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X(0,0) = 8.6 X(0,1) = 3.5 

X(1,0) = 7.3 X(1,1) = 32.6 


With BASIC, you may have as many dimensions in your array as your 
program space allows. Here is an example of a three-dimensional 
array named L which contains these eight elements: 


L(0,0,0) = 35233 
L(0,0,1) = 52000 

L(1,0,0) = 33333 
L(1,0,1) = 53853 


L(0,1,0) = 96522 
L(0,1,1) = 10255 

L(1,1,0) = 96253 
L(1,1,1) = 79654 


BASIC assumes that all arrays contain 11 elements in each 
dimension. If you want more elements you must use the DIM 
statement at the beginning of your program to dimension the array. 


For example, to dimension array L, put this line at the beginning of 
the program: 


DIM l< l»i>1) 


to allow room for two elements in the first dimension; two in the 
second, and two in the third for a total of 2*2*2 = 8 elements. 


How BASIC Stores Data 

The way BASIC stores data determines the amount of memory it 
consumes and the speed in which BASIC can process it. 




Numeric Data 

,You may get BASIC to store all numbers in your program as either 
integer, single precision, or double precision. In deciding how to get 
BASIC to store your numeric data, remember the tradeoffs. Integers 
are the most efficient and the least precise. Double precision is the 
most precise and least efficient. 

Integers 

(Fastest in Computations, Limited in Range) 

To be stored as an integer, a number must be whole and in the range 
of - 32768 to 32767. An integer value requires two byte§ of memory 
for storage. Arithmetic operations are faster when both operands are 
integers. 

For example: 

1 3200 -2 500 -12345 

can all be stored as integers. 
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Single Precision 

(General Purpose, Full Numeric Range) 

Single-precision numbers can include up to seven significant digits, 
and can represent normalized values* with exponents up to 38, i.e., 
numbers in the range: 

[-1 x 10 38 ,-1 x 10- 38 ] [1 x 10 38 ,1 x 10- 38 ] 

If a number is raised to a power greater than 38, an “Overflow” error 
occurs. If it is raised to a power lower than - 38, no errors are 
generated and program execution continues. 

A single-precision value requires four bytes of memory for storage. 
BASIC assumes a number is single precision if you do not specify the 
level of precision. 

* In this manual, normalized value is one in which exactly one digit 
appears to the left of the decimal point. For example, 12.3 expressed 
in normalized form is 1.23 x 10. 

For example: 

10.001 -200034 1.774E6 6.024E-23 123.4567 

can all be stored as single-precision values. But even though BASIC 
stores a number with up to seven digits of precision, when printing it, 
only six digits are shown. 

NOTE: When used in a decimal number, the symbol E stands for 
“single-precision times 10 to the power of..Therefore 6.024E-23 
represents the single-precision value: 

6.024 x 10~ 23 
Double Precision 

(Maximum Precision, Slowest in Computations) 

Double-precision numbers can include up to 16 significant digits, and 
can represent values in the same range as that for single-precision 
numbers. A double-precision value requires eight bytes of memory for 
storage. Arithmetic operations involving at least one double-precision 
number are slower than the same operations when all operands are 
single precision or integer. 

For example: 

1010234578 

-8.7777651010 

3.141592653589793 

8.00100708D12 

can all be stored as double-precision values. 

NOTE: When used in a decimal number, the symbol D stands for 
“double precision times 10 to the power of...” Therefore 
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8.00100708D12 represents the value 
8.00100708 x 10 12 

Strings 

Strings (sequences of characters) are useful for storing non-numeric 
information such as names, addresses, or text. You may store ASCII 
characters, as well as any of the graphic and non-ASCII symbols, in a 
string. (A list of Character Codes is included in Appendix C). 

For example, the data constant: 

Jack Brown, Age 38 

can be stored as a string of 18 characters. Each character (and 
blank) in the string is stored as an ASCII code, requiring one byte of 
storage. 

BASIC would store the above string constant internally as: 


Hex 

Code 

4A 

61 

63 

6B 

20 

42 

72 

6F 

n 

nr 

QJ& 

2C 

20 

41 

67 

65 

20 

33 

38 

ASCII 

Char¬ 

acter 

J 








W 

n 

l 


A 

9 

e 


3 

8 


A string can be up to 255 characters long. Strings with length zero 
are called “null” or “empty”. 




How BASIC Classifies Constants 

When BASIC encounters a data constant in a statement, it must 
determine the type of the constant: string, integer, single precision, or 
double precision. First, we will list the rules BASIC uses to classify the 
constant. Then we will show you how you can override these rules, if 
you want a constant stored differently: 

Rule 1 

If the value is enclosed in double-quotes, it is a string. 

For example: 

“YES” 

“3331 Waverly Way” 

“1234567890” 

are all classified as strings. 

Rule 2 

If the value is not in quotes, it is a number. (An exception to this rule 
is during data input by an operator, and in DATA lists. See INPUT, 
INKEY$, and DATA) 
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For example: 

123001 

1 

— 7.3214E + 6 
are all numeric data. 

Rule 3 

Whole numbers in the range of - 32768 to 32767 are integers. 

For example: 

12350 

-12 

10012 

are integer constants. 

NOTE: If you enter a number as a constant in response to a 
command that calls for an integer, and the number is out of integer 
range, BASIC converts the number to single or double precision. 

When the number is printed, it appears with a type-declaration tag at 
the end. 

Rule 4 

If the number is not an integer and contains seven or fewer digits, it is 
single precision. 

For example: 

1234567 

-1.23 

1.3321 

are ail classified as single precision. 

Rule 5 

If the number contains more than seven digits, it is double precision. 
For example, these numbers: 

1234567890123456 
— 1000000000000.1 
2.777000321 

are all classified as double precision. 

Type Declaration Tags 

You can override BASIC’s normal typing criteria by adding the 
following “tags” at the end of the numeric constant: 

! Makes the number single precision. For example, in the 
statement: 

sJ 
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A = 12*345678301234! 

BASIC classifies the constant as single precision, and shortens it 
to seven digits. However, if you tell BASIC to print the value of A, 
only six digits are printed out: 

12.3457 

E Single-precision exponential format. The E indicates that the 
constant is to be multiplied by a specific power of 10. For 
example: 

A = 1.2E5 

stores the single-precision number 120000 in A. 

# Makes the number double precision. For example, in statement: 
PRINT 3#/7 

BASIC classifies the first constant as double precision before the 
division takes place. 

D Double-precision exponential format. The D indicates the 
constant is to be multiplied by a specified power of 10. For 
example, in: 

A = 1.23456789D - 1 

the double-precision constant has the value 0.123456789. 

How BASIC Classifies Variables 

When BASIC encounters a variable name in the program, it classifies 
it as either a string, an integer, a single-precision number, or a 
double-precision number. 

BASIC classifies all variable names as single-precision initially. For 
example: 

AB AMOUNT XY L 
are all single precision initially. If this is the first line of your program: 
LP = 1.2 

BASIC classifies LP as a single-precision variable. 

However, you may assign different attributes to variables by using 
definition statements at the beginning of your program: 

DEFINT - Defines variables as integer 
DEFDBL - Defines variables as double-precision 
DEFSTR - Defines variables as string 
DEFSNG - Defines variables as single-precision. (Since BASIC 
classifies all variables as single precision initially 
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anyway, you would only need to use DEFSNG if one 
of the other DEF statements was used). 





For example: 

DEFSTR L 

makes BASIC classify all variables which start with L as string 
variables. After this statement, the variables: 

L LP LAST 

can all hold string values only. 

Type Declaration Tags 

As with constants, you can always override the type of a variable 
name by adding a type declaration tag at the end. The four types of 
declaration tags for variables are: 

% Integer 
I Single precision 
# Double precision 
$ String 

For example: 

1% FT% NUM% COUNTER% 

are all integer variables, regardless of what attributes have been 
assigned to the letters I, F, N, and C. 

T! RY! QUAN! PERCENT! 

are all single-precision variables, regardless of what attributes have 
been assigned to the letters T, R, Q, and P. 

X# RR# PREV# LSTNUM# 

are all double-precision variables, regardless of what attributes have 
been assigned to the letters X, R, P, and L. 

Q$ CA$ WRD$ ENTRY$ 

are all string variables, regardless of what attributes have been 
assigned to the letters Q, C, W, and E. 

Note that any given variable name can represent four different 
variables. For example: 

A5# A5! A5% A5$ 

are all valid and distinct variable names. 

One further implication of type declaration: Any variable name 
used without a tag is equivalent to the same variable name used with 
one of the four tags. For example, after the statement: 
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DEFSTR C 

the variable referenced by the name Cl is identical to the variable 
referenced by the name C1$. 

How BASIC Converts Numeric Data 

Often your program might ask BASIC to assign one type of constant 
to a different type of variable. For example: 

AX = 2.34 

In this example, BASIC must first convert the single-precision constant 
2.34 to an integer in order to assign it to the integer variable A%. 

You might also want to convert one type of variable to a different 
type, such as: 

A# = AX 
A! = A» 

A! = AX 

The conversion procedures are explained on the following pages. 

Single or double precision to integer type 

BASIC rounds the fractional portion of the number. 

NOTE: The original value must be greater than or equal to -32768, 
and less than 32768. 

Examples 

AX = 32766.7 
assigns A% the value 32767. 

AX = 2.5D3 

assigns A% the value 2500. 

AX = -123.45678901234578 
assigns A% the value -123. 

AX = -32768.5 

produces an Overflow Error (out of integer range). 

Integer to single or double precision 

No error is introduced. The converted value looks like the original 
value with zeros to the right of the decimal place. 

Examples 

A# = 32767 

Stores 32767.000000000000 in A#. 







A! = -1234 
Stores -1234.000 in A!. 

Double to single precision 

This involves converting a number with up to 16 significant digits into 
a number with no more than seven digits. BASIC rounds the number 
to seven significant digits. Before printing it, BASIC rounds it off to six 
digits. 

Examples 

A! = 1.2345G7890124567 
stores 1.234568 in A!. However, the statement: 

PRINT A 

displays the value 1.23457, because only six digits are displayed The 
full seven digits are stored in memory. 

A! = 1.3333333333333333 

stores 1.333333 in A!. 

Single to double precision 

To make this conversion, BASIC simply adds trailing zeros to the 
single-precision number. If the original value has an exact binary 
representation in single-precision format, no error is introduced. For 
example: 

A# = 1.5 

stores 1.5000000000000 in A#, since 1.5 does have an exact binary 
representation. 

However, for numbers which have no exact binary representation, an 
error is introduced when zeros are added. For example: 

a# = 1.3 

stores 1.299999952316284 in A#. 

Because most fractional numbers do not have an exact binary 
representation, you should keep such conversions out of your 
programs. For example, whenever you assign a constant value to a 
double-precision variable, you can force the constant to be double 
precision: 

a# = 1.3# A# = 1.3D 

both store 1.3 in A#. 

Here is a special technique for converting a single precision value to 
double precision, without introducing an error into the double-precision 
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value. It is useful when the single-precision value is stored in a 
variable. 

Take the single-precision variable, convert it to a string with STR$, 
then convert the resultant string back into a number with VAL. That is, 
use: 


VAL(STR$(single-precision variable)) 

For example, the following program: 

10 A! = 1.3 
20 A# = A! 

30 PRINT A# 

prints a value of: 

1.299999952316284 

Compare with this program: 

10 A! = 1.3 

20 A« = VAL(STR$(A!)) 

30 PRINT A# 

which prints a value of: 

1.3 


The conversion in line 20 causes the value in A! to be stored 
accurately in double-precision variable A#. 

Illegal Conversions 

BASIC cannot automatically convert numeric values to string, or vice 
versa. For example, the statements: 

A$ = 1234 
AX = "1234" 

are illegal. They would return a “Type mismatch” error. (Use STR$ 
and VAL to accomplish such conversions.) 


C- How BASIC Manipulates Data 

You have many fast methods you may use to get BASIC to count, 
sort, test, and rearrange your data. These methods fall into two 
categories: 

1. Operators 

a. numeric 

b. string 

c. relational 

d. logical 

2. Functions 
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Operators 

An operator is the single symbol or word which signifies some action 
to be taken on either one or two specified values referred to as 
operands. 

In general, an operator is used like this: 

operand-1 operator operand-2 

6 + 2 

The addition operator + connects or relates its two operands, 6 and 
2, to produce the result 8. 

Operand-1 and -2 can be expressions. 

A few operations take only one operand, and are used like this: 

operator operand 

5 

The negative operator - acts on single operand 5 to produce the 
result negative 5. 

Neither 6 + 2 nor -5 can stand alone; they must be used in 
statements to be meaningful to BASIC. For example: 

A = 6 + 2 
PRINT -5 

Operators fall into four categories: 

• Numeric 

• String 

• Relational 

• Logical 

based on the kinds of operands they require and the results they 
produce. 

Numeric Operators 

Numeric Operators are used in numeric expressions. Their operands 
must always be numeric, and the results they produce is one numeric 
data item. 

In the description below, we use the terms integer, single-precision, 
and double-precision operations. Integer operations involve two-byte 
operands, single-precision operations involve four-byte operands, and 
double-precision operations involve eight-byte operands. The more 
bytes involved, the slower the operation. 

There are five different numeric operators. Two of them, sign + and 
sign -, are unary, that is, they have only one operand. A sign 
operator has no effect on the precision of its operand. 
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For example, in the statement: 

PRINT -77 * +77 

the sign operators - and + produce the values negative 77 and 
positive 77, respectively. 

NOTE: When no sign operator appears in front of a numeric term, + 
is assumed. 

The other numeric operators are all binary, that is, they all take two 
operands. 

These operators are, in order of precedence: 

" Exponentiation 

*, / Multiplication, Division 

+ ,- Addition, Subtraction 

Exponentiation 

The symbol * denotes exponentiation. It converts both its operands 
to single precision and returns a single-precision result. 

NOTE: To enter the " operator, press (CLEAR) fT). 

For example: 

PRINT 6*.3 

prints 6 to the .3 power. 

Multiplication 

The * operator is the symbol for multiplication. Once again, BASIC 
uses the precision of the more precise operand to perform the 
operation (the less precise operand is converted). 

Examples: 

PRINT 33 * 111 
integer multiplication is performed. 

PRINT 33 * 11.1 

single-precision multiplication is performed. 

PRINT 12*345678901234567 * 11 
double-precision multiplication is performed. 

Division 

The / symbol is used to indicate ordinary division. Both operands are 
converted to single precision or double precision, depending on their 
original precision: 
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• If either operand is double precision, then both are converted to 
double precision and eight-byte division is performed. 

• If neither operand is double precision, then both are converted to 
single precision and four-byte division is performed. 

Examples: 

PRINT 3/4 

single-precision division is performed. 

PRINT 3.8/4 

single-precision division is performed. 

PRINT 3/1.2345878901234567 
double-precision division is performed. 

Addition 

The + operator is the symbol for addition. The addition is done with 
the precision of the more precise operand (the less precise operand is 
converted). 

For example, when one operand is integer type and the other is 
single precision, the integer is converted to single precision and 
four-byte addition is performed. When one operand is single precision 
and the other is double precision, the single-precision number is 
converted to double precision and eight-byte addition is performed. 

Examples: 

PRINT 2+3 
integer addition is performed. 

PRINT 3.1 + 3 

single-precision addition is performed. 

PRINT 1.2345678901234567 + 1 
double-precision addition is performed. 


Subtraction 

The - operator is the symbol for subtraction. As with addition, the 
operation is done with the precision of the more precise operand (the 
less precise operand is converted). 

Examples: 

PRINT 33 - 11 


integer subtraction is performed. 
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PRINT 33 - 11.1 

single-precision subtraction is performed. 

PRINT 12.345678901234567 - 
double-precision subtraction is performed. 


li 



String Operator 

BASIC has a string operator (+) which allows you to concatenate 
(link) two strings into one. This operator should be used as part of a 
string expression. The operands are both strings and the resulting 
value is one piece of string data. 

The + operator links the string on the right of the sign to the string on 
the left. For example: 

PRINT "CATS" + "LOVE" + "MICE" 

prints: 

CATSLOVEMICE 

Since BASIC does not allow one string to be longer than 255 
characters, you will get an error if your resulting string is too long. 

Relational Operators 

Relational operators compare two numerical or two string expressions 
to form a relational expression. This expression reports whether the 
comparison you set up in your program is true or false. It returns a 
-1 if the relation is true; a 0 if it is false. 


Numeric Relations 


This is the meaning of the operators when you use them to compare 
numeric expressions: 


< 

Less than 

> 

Greater than 

= 

Equal to 

< > or > < 

Not equal to 

= < or < = 

Less than or 

= > or > = 

Greater than 

Examples of true relational expressions: 


equal to 
or equal to 


1 < 2 
2 0 5 
2 <= 5 
2 < = 2 
5 > 2 

7 = 7 
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String Relations 

The relational operators for string expressions are the same as 
above, although their meanings are slightly different. Instead of 
comparing numerical magnitudes, the operators compare their ASCII 
sequence. This allows you to sort string data: 

< Precedes 

> Follows 

> < or < > Does not have the same precedence 

<= Precedes or has the same precedence 

>= Follows or has the same precedence 

BASIC compares the string expressions on a character-by-character 
basis. When it finds a non-matching character, it checks to see which 
character has the lower ASCII code. The character with the lower 
ASCII code is the smaller (precedent) of the two strings. 

NOTE: Appendix C contains a listing of ASCII codes for each 
character. 

Examples of true relational expressions: 

“A” < “B” 


The ASCII code for A is decimal 65; for B it’s 66. 
“CODE” < “COOL” 


The ASCII code for O is 79; for D it’s 68. 


If while making the comparison, BASIC reaches the end of one string 
before finding non-matching characters, the shorter string is the 
precedent. For example: 

“TRAIL” < “TRAILER” 


Leading and trailing blanks are significant. For example: 

“ A” < "A” 

ASCII for the space character is 32; for A, it’s 65. 

“Z-80” < “Z-80A” 

The string on the left is four characters long; the string on the right is 
five. 


How to Use Relational Expressions 

Normally, relational expressions are used as the test in an IF/THEN 
statement. For example: 

IF A = 1 THEN PRINT "CORRECT" 

BASIC tests to see if A is equal to 1. If it is, BASIC prints the 
message. 
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IF A* < B$ THEN 50 

if string A$ alphabetically precedes string B$, then the program 
branches to line 50. 

IF R$ = "YES" THEN PRINT A$ 

if R$ equals YES then the message stored as A$ is printed. 

However, you may also use relational expressions simply to return the 
true or false results of a test. For example: 

PRINT 7=7 

prints - 1 since the relation tested is true. 

PRINT "A" > "B" 

prints 0 because the relation tested is false. 

Logical Operators 

Logical operators make logical comparisons. Normally, they are used 
in IF/THEN statements to make a logical test between two or more 
relations. For example: 

IF A = 1 OR C = 2 THEN PRINT X 

The logical operator, OR, compares the two relations A = 1 and 
C = 2. 

Logical operators may also be used to make bit comparisons of two 
numeric expressions. 

For this application, BASIC does a bit-by-bit comparison of the two 
operands, according to predefined rules for the specific operator. 

NOTE: The operands are converted to integer type, stored internally 
as 16-bit, two’s complement numbers. To understand the results of 
bit-by-bit comparisons, you need to keep this in mind. 

The following table summarizes the action of Boolean operators in bit 
manipulation. 
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Meaning of 

Operator Operation 

AND When both bits 

are 1, the re¬ 
sults will be 1. 
Otherwise, the 
result will be 0. 

OR Result will be 1 

unless both bits 
are 0. 


NOT Result is oppo¬ 

site of bit. 


First 

Second 


Operand 

Operand 

Result 

1 

1 

1 

1 

0 

0 

0 

1 

0 

0 

0 

0 

1 

1 

1 

1 

0 

1 

0 

1 

1 

0 

0 

0 

1 


0 

0 


1 


Hierarchy of Operators 

When your expressions have multiple operators, BASIC performs the 
operations according to a well-defined hierarchy so that results are 
always predictable. 


Parentheses 

When a complex expression includes parentheses, BASIC always 
evaluates the expressions inside the parentheses before evaluating 
the rest of the expression. For example, the expression: 

8 - (3 - 2) 

is evaluated like this: 

3-2=1 

8-1=7 

With nested parentheses, BASIC starts evaluating the innermost level 
first and works outward. For example: 

4 * (2 - (3 - 4)) 

is evaluated like this: 

3 - 4 = -1 

2 - (-1) = 3 

4 * 3 = 12 


Order of Operations 

When evaluating a sequence of operations on the same level of 
parentheses, BASIC uses a hierarchy to determine what operation to 
do first. 
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The two listings below show the hierarchy BASIC uses. Operators are 
shown in decreasing order of precedence and are executed as 
encountered from left to right: 

For Numeric Operations: 


( ) (Parentheses) 

“ (Exponentiation) 

+, - (Unary sign operands [not addition and 
subtraction]) 

*,/ (Multiplication and division) 

+, - (Addition and subtraction) 

<,>, = ,< = ,> = ,<> 

NOT 

AND 

OR 

XOR 

EQV 

IMP 


For String Operations: 

+ 

For example, in the line: CS 

X*X + 5*2.8 

BASIC finds the value of 5 to the 2.8 power. Next it multiplies X*X, 
and finally it adds the value of 5 to the 2.8. If you want BASIC to 
perform the indicated operations in a different order, you must add 
parentheses. For example: 

X* (X + 5)''2.8 

or 

X*X + (5 “2.8) 

Here’s another example: 

IF X + 0 OR Y > 0 AND Z = 1 THEN GOTO 255 

The relational operators = and > have the highest precedence, so 
BASIC performs them first, one after the next, from left to right. Then 
the logical operations are performed. AND has a higher precedence 
than OR, so BASIC performs the AND operation before OR. 

If the above line looks confusing because you can’t remember which 
operator is precedent over which, then you can use parentheses to 
make the sequence obvious: 

IF X = 0 OR ((Y > 0) AND (Z = 1)) THEN GOTO 255 
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Functions 

A function is a built-in sequence of operations which BASIC performs 
on data. BASIC functions save you from having to write a BASIC 
routine, and they operate faster than a BASIC routine would. 

Examples: 

SQR (A + 6) 

tells BASIC to compute the square root of (A + 6). 

MID$ (A$ »3 >2) 

tells BASIC to return a substring of the string A$, starting with the 
third character, with a length of 2. 

BASIC functions are described in more detail in Chapter 7. 

If the function returns numeric data, it is a numeric function and may 
be used in a numeric expression. If it returns string data, it is a string 
function and may be used in a string expression. 




D- How to Construct an Expression 

Understanding how to construct an expression will help you put 
together powerful statements — instead of using many short ones. In 
this section we will discuss the two kinds of expressions you may 
construct: 

• Simple 

• Complex 

as well as how to construct a function. 

As we have stated before, an expression is actually data. This is 
because once BASIC performs all the operations, it returns one data 
item. An expression may be string or numeric. It may be composed 
of: 

• Constants 

• Variables 

• Operators 

• Functions 

Expressions may be either simple or complex: 

A simple expression consists of a single term: a constant, variable 
or function. If it is a numeric term, it may be preceded by an optional 
+ or - sign, or by the logical operator NOT. 

For example: 

+ A 3.3 -5 SQR(8) 

are all simple numeric expressions, since they only consist of one 
numeric term. 
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A$ STRINGS (20,A$) "WORD” "M” 

are all simple string expressions, since they only consist of one string 
term. 

Here’s how a simple expression is formed: 


r€H 


r>NOT- 


+ CONSTANT -I 





VARIABLE 

FUNCTION -1 


A complex expression consists of two or more terms (simple 
expressions) combined by operators. For example: 

A-1 X + 3.2-Y 1=1 A AND B ABS(B) + LOG(2) 

are all examples of complex numeric expressions. (Notice that you 
can use the relational expression (1=1) and the logical expression (A 
AND B) as a complex numeric expression since both actually return 
numeric data.) 

A$ + B$ “Z” + Z$ STRING$(10, “A”) + “M” 
are all examples of complex string expressions. 

This is how a complex numeric expression is formed: 
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This is how a complex string expression is formed: 



Most functions, except functions returning system information, require 
that you input either or both of the following kinds of data: 

• One or more numeric expressions 

• One or more string expressions 

This is how a function is formed: 

W 



If the data returned is a number, the function may be used as a term 
in a numeric expression. If the data is a string, the function may be 
used as a term in a string expression. 

SIN(A) STR$(X) VAL(A) LOG(.53) 
are all examples of functions. 
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Chapter 5/ Disk Files 


SJ 


You may want to store data on your disk for future use. To do this, 
you need to store the data in a “disk file.” A disk file is an organized 
collection of related data. It may contain a mailing list, a personnel 
record, or almost any kind of information. This is the largest block of 
information on disk that you can address with a single command. 

To transfer data from a BASIC program to a disk file, and vice-versa, 
the data must first go through a “buffer”. This is an area in memory 
where data is accumulated for further processing. 

With BASIC, you can create and access two types of disk files. The 
difference between these two types is that each is created in a 
different “mode.” The mode you choose determines what kind of 
access you will have to the file: sequential access or direct access. 


Sequential-Access Files 

With a sequential-access file, you can only access data in the same 
order it was stored: sequentially. To read from or write to a particular 
section in the file, you must first read through all the contents in the 
file until you get to the desired section. 

Data is stored in a sequential file as ASCII characters. Therefore, it is 
ideal for storing free-form data without wasting space between data 
w items. However, it is limited in flexibility and speed. 

The statements and functions used with sequential files are: 

OPEN WRITE# EOF 

PRINT# INPUT# LOC 

PRINT# USING LINE INPUT# CLOSE 

These statements and functions are discussed in more detail in 
Chapters 6 and 7. 

Creating a Sequential-Access File 

1. To create the file, OPEN it in “O” (output) mode and assign it a 
buffer number (from 1 to 15). 

Example 

OPEN ”0"* 1» "LIST/EMP" 

opens a sequential output file named LIST/EMP and gives buffer 1 

access to this file. 

2. To input data from the keyboard into one or more program 
variables, use either INPUT or LINE INPUT. (The difference 
between these two statements is that each recognizes a different 
set of “delimiters”. Delimiters are characters that define where a 
data item begins or ends). 
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Example 

LINE INPUT* “NAME? "5 N$ 
inputs data from the keyboard and stores it in variable N$. 

3. To write data to the file, use the WRITE# statement (you can also 
use PRINT#, but make sure you delimit the data). 

Example 

WRITE# 1 * N$ 

writes variable N$ to the file, using buffer 1 (the buffer used to 
OPEN the file). Remember that data must go through a buffer 
before it can be written to a file. 

4. To ensure that all the data was written to the file, use the CLOSE 
statement. 

Example 

CLOSE 1 

closes access to the file, using buffer 1 (the same buffer used to 
OPEN the file). 

Sample Program 

10 OPEN "0“» 1» "LIST/EMP" 

20 LINE INPUT "NAME? "5N$ 

30 IF N$ = "DONE" THEN G0 
40 tm-T-i# 1 » N* 

50 PRINT: GOTO 20 

60 CLOSE 1 

RUN 

NOTE: The file “LIST/EMP” stores the data you input through the 
aid of the program, not the program itself (the program 
manipulates data). To save the program above, you must assign it 
a name using the SAVE command (refer to Chapter 1). 

Example 

SAUE "PAYROLL" 

would save the program under the name “PAYROLL”. 

NOTE: Every time you modify a program, you must SAVE it again 
(you can use the same name); otherwise, the original program 
remains on disk, without your latest corrections. 


5. To access data in the file, reOPEN it in the “I” (input) mode. 

Example 

OPEN "I"* 1* "LIST/EMP" 
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OPENs the file named LIST/EMP for sequential input, using 
buffer 1. 

6. To read data from the file and assign it to program variables, use 
either INPUT# or LINE INPUT#. 

Examples 

INPUT* 1» N* 

reads a string item into N$, using buffer 1 (the buffer used when 
the file was OPENed). 

LINE INPUT# 1> N$ 

reads an entire line of data into N$, using buffer 1. 

INPUT# and LINE INPUT# each recognize a different set of 
“delimiters” for reading data from the file. Delimiters are characters 
that define the beginning or end of a data item. See Chapter 7 for 
a detailed explanation of these statements. 

Sample Program 

10 OPEN “I"* 1 * "LIST/EMP" 

20 IF EOF(1)» THEN 100 
30 INPUT# 1» N$ 

40 PRINT N* 

50 GOTO 20 
100 CLOSE 

Updating a Sequential-Access File 

1. To add data to the file, OPEN it in “E” (extend) mode. 

OPEN "E"» 1» "LIST/EMP" 

opens the file LIST/EMP so that it can be extended. The data you 
enter is appended to LIST/EMP. 

2. To enter new data to the file, follow the same procedure as for 
entering data in “0” mode. 

The following program illustrates this technique. It builds Upon the 
file we previously created under the name LIST/EMP. 

NOTE: Read through the entire program first. If you encounter 
BASIC words (commands or functions) that are unfamiliar to you, 
refer to Chapter 7 for their definitions. 

NEW 

10 OPEN "E"> 1» "LIST/EMP" 

20 LINE INPUT "TYPE A NEW NAME OR PRESS <N>"5 N$ 
30 IF N$ = "N" THEN G0 
40 WRITE# 1> N$ 

50 GOTO 20 
G0 CLOSE 
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If you want the program to print on your display the information 
stored in the updated file, add the following lines: 

70 OPEN "I"* 1 t "LIST/EMP" 

80 IF EOF( 1 ) THEN 2000 
30 INPUT# 1 , N$ 

100 PRINT N$ 

110 GOTO 80 
2000 CLOSE 
RUN 

Once you have RUN this program, SAVE it. 

Example 

SAUE "PAYROLLS 11 ' saues the new program 


Direct-Access Files 


With a direct-access file, you can access data almost anywhere on 
disk. It is not necessary to read through all the information, as with a 
sequential-access file. This is possible because in a direct-access file, 
information is stored and accessed in distinct units called “records”. 
Each record is numbered. 

Creating and accessing direct-access files requires more program 
steps than sequential-access files. However, direct-access files are 
more flexible and easier to update. 

One important note: BASIC allocates space for records in numeric 
order. That is, if the first record you write to the file is number 200, 
BASIC allocates space for records 0 through 199 before storing 
record 200 in the file. 

The maximum number of logical records is 65,535. Each record may 
contain between 1 and 256 bytes. 

The statements and functions used with direct-access files are: 


OPEN 

GET 

LOC 

MKS$ 

CVS 


FIELD 

PUT 

MKD$ 

CVD 


LSET/RSET 

CLOSE 

MKI$ 

CVI 


These statements and functions are discussed in more detail in 
Chapters 6 and 7. 

Creating a Direct-Access File 

1. To create the file, OPEN it for direct access in “D” mode (“R” may 
also be used. It stands for “random access”, which is simply 
another name for direct access). 
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Example 

□ PEN . "D" » 1 » "LISTING" t 32 

opens the file named “LISTING”, gives buffer 1 direct access to 
the file, and sets the record length to 32 bytes. (If the record length 
is omitted, the default is 256 bytes). Remember that data is 
passed to and from disk in records. 

2. Use the FIELD statement to allocate space in the buffer for the 
variables that will be written to the file. This is necessary because 
you must place the entire record into the buffer before putting it 
into the disk file. 

Example 

FIELD 1. 20 AS N*» 4 AS A* .8 AS P* 

allocates the first 20 positions in buffer 1 to string variable N$, the 
next four positions to A$, and the next eight positions to P$. N$, 

A$ and P$ are now “field names”. 

3. To move data into the buffer, use the LSET statement. Numeric 
values must be converted into strings when placed in the buffer. 

To do this, use the “make” functions: MKI$ to make an integer 
value into a string, MKS$ for a single-precision value, and MKD$ 
for a double-precision value. 

Example 

LSET N$ = X$ 

LSET A*=MKS*(AMT) 

4. To write data from the buffer to a record (within a direct-access 
disk file), use the PUT statement. 

put l» CODE* 

writes the data from buffer 1 to a record with the number CODE%. 
(The percentage sign at the end of a variable specifies that it is an 
integer variable.) 

The following program writes information to a direct-access file: 

10 OPEN "D" , 1, "LISTING"t 32 
20 FIELD It 20 AS N$ t 4 AS A* t 8 AS P* 

30 INPUT "2-DIGIT CODEt 0 TO END"! CODE* 

40 IF CODE* = 0 THEN 130 
50 INPUT "NAME"! X* 

60 INPUT "AMOUNT"; AMT 
70 INPUT "PHONE"! TEL* 

80 LSET N* = X* 

90 LSET A* = MKS*(AMT) 

100 LSET P* = TEL* 

110 PUT 1» CODE* 

120 GOTO 30 
130 CLOSE 1 
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The two-digit code that you enter in line 30 becomes a record 
number. That record number will store the name(s), amount(s) and 
phone number(s) you enter when lines 50, 60 and 70 are 
executed. The record is written to the file when BASIC executes 
the PUT statement in line 110. 

After typing this program, SAVE it and RUN it. Then, enter the 
following data: 

2-DIGIT CODE, 0 TO END? 20 

NAME? SMITH 

AMOUNT? 34.55 

PHONE? 567-9000 

2-DIGIT CODE » 0 TO END? 0 

BASIC stored SMITH, 34.55, and 567-9000 in record 20 of file 
LISTING. 

Accessing a Direct-Access File 

1. OPEN the file in “D” mode (“R” can also be used). 

Example 

OPEN "D"» 1»"FILE"»32 

2. Use the FIELD statement to allocate space in the buffer for the 
variables that will be read from the file. 

Example 

FIELD 1 * 20 AS N$. 4 AS A$» 8 AS P$ 

3. Use the GET statement to read the desired record from a direct 
disk file into a buffer. 

Example 

GET 1» CODEX 

gets the record numbered CODE% and reads it into buffer 1. 

4. Convert string values back to numbers using the “convert” 
functions: CVI for integers, CVS for single-precision values, and 
CVD for double-precision values. 

Example 

PRINT N$ 

PRINT CVS(At) 

The program may now access the data in the buffer. 

The following program accesses the direct-access file “LISTING” 
(created with the previous program). When BASIC executes line 
30, enter any valid record number from “LISTING”. This program 
will print the contents of that record. 
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10 OPEN "D"» 1# “LISTING"» 32 
20 FIELD 1>20 AS N$>4 AS A$ >8 AS P$ 

30 INPUT "2-DIGIT CODE> 0 TO END"! CODEX 
35 IF CODEX = 0 THEN 1000 
40 GET #1> CODEX 
50 PRINT N$ 

60 PRINT USING "$$#.##"! CUS(A$) 

70 PRINT P$: PRINT 
80 GOTO 30 
1000 CLOSE 1 

After typing this program, SAVE it and RUN it. When BASIC asks 
you to enter a 2-digit code, enter 20 (the record we created 
through the previous program). Your display should show: 

2-DIGIT CODE > 0 TO END? 20 

SMITH 

$34.55 

5G7-9000 

If you entered a record number which is not a part of “LISTING”, 
your display would show: 

$0.00 

If you wanted to go back and update “LISTING”, simply LOAD the 
w previous program (the one that created “LISTING”) and RUN it. 
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Chapter 6/ Introduction To 
BASIC Statements And Functions 


BASIC is made up of keywords. These keywords instruct the 
computer to perform certain operations. 

Chapter 7 describes all of BASIC’s keywords. This chapter explains 
the format used in Chapter 7. It also introduces you to BASIC’s two 
types of keywords: statements and functions. 


Format for Chapter 7 

Keyword 


Syntax parameters) or ( arguments)) 


Brief definition of keyword. 

Detailed definition of keyword. 

Example(s) 

Sample Program(s) 

This format varies slightly, depending on the complexity of each 
keyword. For instance, some keywords are used alone (without 
parameters or arguments). Others have several possible syntaxes. As 
a general rule, definitions for statements are longer than definitions for 
functions. That is because a statement is a complete instruction to 
BASIC, while a function is a built-in subroutine which may only be 
used as part of a statement. 

Some keywords have several sample programs, others don’t have 
any at all. We added programs to illustrate useful applications which 
may not be readily apparent. Remember that this manual is to be 
used as a reference, not a tutorial on how to program in BASIC. 

IMPORTANT NOTE: BASIC for TRSDOS Version 6 requires that 
keywords be delimited by spaces. This means that you must leave a 
space between a keyword and any variables, constants or other 
keywords. The only exceptions to this rule are characters which are 
shown as part of the syntax of the keyword. 

For example, if you typed: 

DELETE. 

BASIC would return a “Syntax error.” You must leave a blank space 
between the word DELETE and the period. 

For a definition of the terms and notation used in Chapter 7, see page 
2-4 of the Introduction. 
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Statements 

A program is made up of lines; each line contains one or more 
statements. A statement tells the computer to perform some operation 
when that particular line is executed. For example, 

100 STOP 


tells the computer to stop executing the program when it reaches line 
100 . 


Statements for assigning values to variables and defining memory 
space: 


CLEAR 

COMMON 

DATA 

DEFDBL 
DEF FN 

DEFINT 

DEFSNG 

DEFSTR 

DEF USR 

DIM 

ERASE 

LET 

MID$ 

OPTION BASE 

RANDOM 

READ 

RESTORE 

SWAP 


clears all variables, allocates memory and 
stack space. 

passes variables to a CHAINed program, 
stores data in your program so that you may 
assign it to a variable, 
defines variables as double precision, 
defines a function according to your 
specifications. 

defines variables as integers, 
defines variables as single precision, 
defines variables as strings, 
defines the entry point for USR routines, 
dimensions an array, 
erases an array. 

assigns a value to a variable (the keyword 
LET may be omitted), 
replaces a portion of a string, 
declares the minimum value for array 
subscripts. 

reseeds the random number generator, 
reads data stored in the DATA statement and 
assigns it to a variable, 
restores the DATA pointer, 
exchanges the values of variables. 


Statements for altering program sequence: 


CHAIN 

END 

FOR/NEXT 

GOSUB 

GOTO 

IF ... THEN ... ELSE 
ON ...GOSUB 


loads another program and passes variables 

to the current program. 

ends a program. 

establishes a program loop. 

transfers program control to the subroutine. 

transfers program control to the specified line 

number. 

evaluates an expression and performs an 
operation if conditions are met. 
evaluates an expression and branches to a 
subroutine. 
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ON ... GOTO evaluates an expression and branches to 

another program line. 

RETURN returns from a subroutine to the calling 

program. 

STOP stops program execution. 

WHILE ... WEND executes statements in a loop as long as a 

given condition is true. 

WAIT suspends program execution while monitoring 

the status of a machine input port. 

Statements for storing and accessing data on disk: 


CLOSE 

FIELD 

GET 

INPUT# 

LINE INPUT# 
LSET 

OPEN 
PRINT# 
PRINT# USING 

PUT 

RSET 

WRITE# 


closes access to a disk file. 

organizes a direct-access buffer. 

gets a record from a direct-access file. 

inputs data from a disk file. 

inputs an entire line from a disk file. 

moves data (and left-justifies it) to a field in a 

direct-access file buffer. 

opens a disk file. 

writes data to a sequential disk file, 
writes data to a disk file using the specified 
format. 

puts a record into a direct-access file, 
moves data (and right-justifies it) to a field in 
a direct-access file buffer, 
writes data to a sequential file. 


Statements for debugging a program: 


CONT continues program execution. 

ERL returns the line number where an error 

occurred. 

ERR returns an error code after an error. 

ERROR simulates the specified error. 

ON ERROR GOTO sets up an error-trapping routine. 
RESUME terminates an error-handling routine. 

TROFF turns the tracer off. 

TRON turns the tracer on. 


Statements for inputting or outputting data to the video display or the 
line printer: 


CLS 

INPUT 

LINE INPUT 

LIST 

LLIST 

LPRINT 

PRINT 

WRITE 


clears the display. 

inputs data from the keyboard. 

inputs an entire line from the keyboard. 

lists a program to the display. 

lists program to line printer. 

prints data at the line printer. 

prints data to the display. 

prints data on the display. 
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Statements for performing system functions or entering other modes 
of operation: 

AUTO 

automatically numbers program lines. 

CALL 

calls an assembly-language subroutine. 

DELETE 

erases program lines from memory. 

DEF USR 

specifies the starting address of an 
assembly-language subroutine. 

EDIT 

edits program lines. 

KILL 

deletes a disk file. 

LOAD 

loads a program from disk. 

MERGE 

merges a disk program with a resident 
program. 

NAME 

renames a disk file. 

NEW 

erases a program from RAM. 

OUT 

sends a byte to a machine output port. 

POKE 

writes a byte into a memory location. 

RENUM 

renumbers a program. 

RUN 

executes a program. 

SAVE 

saves a program on disk. 

SOUND 

generates a sound 

SYSTEM 

Functions 

returns to TRSDOS. 

A function is a built-in subroutine. It may only be used as part of a 
statement. 

Most BASIC functions return numeric or string data by performing 

certain built-in routines. Special print functions are used to control the 
video display. 

Numeric Functions (return a number): 

ABS 

computes the absolute value. 

ASC 

returns the ASCII code. 

ATN 

computes the arctangent. 

CDBL 

converts to double precision. 

CINT 

returns the largest integer not greater than 
the parameter. 

COS 

computes the cosine. 

CSNG 

converts to single precision. 

EXP 

computes the natural exponential. 

FIX 

truncates to whole number. 

FRE 

returns the number of bytes in memory not 
being used. 

INSTR 

searches for a specified string. 

INP 

returns the byte read from a port. 

INT 

returns the largest whole number not greater 
than the argument. 

LEN 

returns the length of the string. 

LOG 

computes the natural logarithm. 
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MEM 

PEEK 

RND 

SGN 

SIN 

SQR 

TAN 

USR 

VAL 

VARPTR 


returns the amount of memory. 

returns a byte from a memory location. 

returns a pseudorandom number. 

returns the sign. 

calculates the sign. 

calculates the square root. 

computes the tangent. 

calls an assembly-language subroutine. 

returns the numeric value of a string. 

returns an address for a variable or buffer. 


String Functions (return a string value): 


CHR$ 

DATE$ 

ERRS$ 

HEX$ 

LEFT$ 

MID$ 

OCT$ 

RIGHTS 

SPACES 

STRS 

STRINGS 

TIMES 


returns the specified character, 
returns today’s date. 

returns the latest TRSDOS error number and 
message. 

converts a decimal value to a hexadecimal 
string. 

returns the left portion of a string, 
returns the mid-portion of a string, 
converts a decimal value to an octal string, 
returns the right portion of a string, 
returns a string of spaces, 
converts to string type, 
returns a string of characters, 
returns the time. 


Input/Output Functions (perform input/output to the keyboard, display, 
line printer or disk files): 


INKEY$ 

INPUTS 

POS 

ROW 

SPC 

CVD 

CVI 

CVS 

EOF 

INPUTS 

LOC 

LOF 

MKIS 

MKSS 

MKDS 


returns the keyboard character, 
returns a string of characters from the 
keyboard. 

returns the cursor column position on the 
display. 

returns the row position on the display. 

prints spaces to the display. 

restores data from a direct disk file to double 

precision. 

restores data from a direct disk file to integer, 
restores data from a direct disk file to single 
precision. 

checks for end-of-file. 

inputs a string of characters from a sequential 
disk file. 

returns the current disk file record number, 
returns the disk file’s end-of-file. 
converts an integer value to a string for 
writing it to a direct-access disk file, 
converts a single-precision number to a string 
for writing it to a direct-access file, 
converts a double-precision value to a string 
for writing it to a direct-access file. 
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Chapter 7/ Statements And Functions 


O 


ABS 


A BS( number) 


Function 



Computes the absolute value of number. 

ABS returns the absolute value of the argument, that is, the 
magnitude of the number without respect to its sign. 

If number is greater than or equal to zero, ABS (number) = number. If 
number is less than zero, ABS(negative number) = number. 

Example 

X = ABS(Y) 

computes the absolute value of Y and assigns it to X. 

Sample Program 

100 INPUT "WHAT'S THE TEMPERATURE OUTSIDE 
(DEGREES F)"5 TEMP 

110 IF TEMP < 0 THEN PRINT "THAT'S" ABS(TEMP) 
"BELOW ZERO! BRR!": END 
120 IF TEMP = 0 THEN PRINT "ZERO DEGREES! MITE 
COLD!": END 

130 PRINT TEMP "DEGREES ABOVE ZERO? BALMY!": 
END 


w 
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Function 


ASC (string) 


Returns the ASCII code for the first character of string. 

The value is returned as a decimal number. If string is null, an “Illegal 
function call” error occurs. 

Example 

PRINT ASC("A") 

prints 65, the ASCII code for “A”. 

Sample Program 

ASC can be used to make sure that a program is receiving the proper 
input. Suppose you’ve written a program that requires the user to 
input hexadecimal digits 0-9, A-F. To make sure that only those 
characters are input, and exclude all other characters, you can insert 
the following routine. 

100 INPUT "ENTER A HEXADECIMAL UALUE 


(0-9 * A - F)"5N$ 

110 A = ASC(N$) 

120 IF A>47 AND A<58 OR 


'set ASCII code 
A>64 AND A<71 THEN 


PRINT "OK.": GOTO 100 
130 PRINT "VALUE NOT OK." 


GOTO 100 





ATN 


ATN (number) 


Function 


Computes the arctangent of number in radians. 

ATN returns the angle whose tangent is number. The result is always 
single precision, regardless of number’s numeric type. 

To convert this value to degrees, multiply ATN {number) by 57.29578. 

Example 

X = ATN(Y/3) 

computes the arctangent of Y/3 and assigns the value to X. 

w auto 


AUTO [//ne][,Increment] 


Statement 


Automatically generates a line every time you press (ENTER) . 

AUTO begins numbering at line and displays the next line using 
increment. The default for both values is 10. A period (.) can be 
substituted for line. In this case, BASIC uses the current line number. 


IF AUTO generates a line number that has already been used, it 
display s an asterisk after the number. To save the existing line, press 
[ENTER) immediately after the asterisk. AUTO then generates the next 
line number. 


To turn off AUTO, press (BREAK) . The current line is canceled and 
BASIC returns to command level. 
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Examples 

AUTO 

generates lines 10, 20, 30, 40. 

AUTO 100» 50 

generates lines 100, 150, 200, 250 ... 


CALL 


CALL variable [parameter list] 


Statement 


Transfers program control to an assembly-language subroutine stored 
at variable. 

Variable contains the address where the subroutine starts in memory. 

Variable may not be an array variable. 

Parameter list contains the values that are passed to the external 
subroutine. Parameter list may contain only variables. 

A CALL statement with no parameters generates a simple Z-80 
“CALL” instruction. The corresponding subroutine should return with a 
simple “RET”. 

The method for passing parameters depends upon the number of 
parameters to pass: 

1. If the number of parameters is less than or equal to 3, they 
are passed in the registers. HL contains the address pointing 
to parameter 1. DE contains the address pointing to 
parameter 2. BC contains the address pointing to parameter 
3. 

2. If the number of parameters is greater than 3, they are 
passed as follows: 

HL contains the address pointing to parameter 1. 

DE contains the address pointing to parameter 2. 

BC points to the low byte of a contiguous data block 

containing parameters 3 through n (that is, to the low byte of 

parameter 3). -"“v 
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Note that with this scheme, the subroutine must know how many 
parameters to expect in order to find them. The calling program is 
responsible for passing the correct number of parameters. 

When accessing parameters in a subroutine, remember that they are 
pointers to the actual arguments passed. 

NOTE: The number, type and length of the parameters in the calling 
program must match with the parameters expected by the subroutine. 
This applies to BASIC subroutines, as well as those subroutines 
written in assembly language. 

See also USR and VARPTR. 

Example 

110 MYROUT = &HD000 
120 CALL MYROUT(I tJt K) 

We assume that DOOO is the address for an assembly-language 
routine. The values of I, J, and K (which we also assume were given 
elsewhere) are passed to that routine. 


CDBL 

LJ 


CDBL(number) 


Function 


Converts number to double precision. 

CDBL returns a 17-digit value. This function may be useful if you want 
to force an operation to be performed in double precision, even 
though the operands are single precision or integers. 

Sample Program 

210 A=454.G7 

220 PRINT A5 CDBL(A) 

RUN 

454.G7 454.6700134277344 
Ready 
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CHAIN 




Statement 

CHAIN [MERGE ] filespec [,//ne] [,ALL] [.DELETE line-line] 


Loads a BASIC program named filespec, chains it to a “main” 
program, and begins running it. 

Filespec must have been saved in ASCII format before you can 
CHAIN it. To do this, use SAVE with the ‘A’ option. 

Line is the first line to be run in the CHAINed program. If omitted, 
execution begins at the first program line of the CHAINed program. 

The ALL option passes every variable in the main program to the 
chained program. If omitted, the main program must contain a 
COMMON statement to pass variables. If you will be CHAINing 
subsequent programs (and passing variables), each new program 
must contain a COMMON statement. 

The MERGE option “overlays” the lines of filespec with the main 
program. See MERGE to understand how BASIC overlays (merges) 
program lines. 

The DELETE option deletes lines in the overlay so that you can 
MERGE in a new overlay. 

Examples 

CHAIN PRDG2 

loads PROG2, chains it to the main program currently in memory, and 
begins executing it. 

CHAIN SUBPROG/BAS, ALL 

loads, chains and executes SUBPROG/BAS. The values of all the 
variables in the main program are passed to SUBPROG/BAS. 

Sample Program 1 

10 REM THIS PROGRAM DEMONSTRATES CHAINING 
USING COMMON TO PASS VARIABLES. 

20 REM SAVE THIS MODULE ON DISK AS "PR0G1" 

USING THE A OPTION. 

30 DIM A$(2) *B$(2) 

40 COMMON A$()*B$<) 

50 A$(l)="VARIABLES IN COMMON MUST BE ASSIGNED " 




2-70 








G0 A$(2)="VALUES BEFORE CHAINING" 

70 B$ (1 ) ..B$(2) = " " 

80 CHAIN "PR0G2" 

90 PRINT : PRINT B$(l): PRINT : PRINT B*<2): 
PRINT 
100 END 

Save this program as “PROG1”, using the ‘A’ option (Type: SAVE 
filespec, A). Type NEW, then enter the following program. 

10 REM THE STATEMENT "DIM A$(2)»B$(2>" MAY 
ONLY BE EXECUTED ONCE. 

20 REM HENCE* IT DOES NOT APPEAR IN THIS 
MODULE. 

30 REM SAVE THIS MODULE ON THE DISK AS "PR0G2" 
USING THE A OPTION. 

40 COMMON A$<) *B$( ) 

50 PRINT: PRINT A$(1)!A$(2) 

60 B$(1)="NOTE HOW THE OPTION OF SPECIFYING A 
STARTING LINE NUMBER" 

70 B$(2)="WHEN CHAINING AVOIDS THE DIMENSION 
STATEMENT IN 'PR0G1'." 

80 CHAIN "PROG1" *90 
90 END 

Save this program as “PROG2”, using the ‘A’ option. Load PROG1 
and run it. Your screen should display: 

VARIABLES IN COMMON MUST BE ASSIGNED VALUES 
BEFORE CHAINING. NOTE HOW THE OPTION OF 
SPECIFYING A STARTING LINE NUMBER WHEN 
CHAINING AVOIDS THE DIMENSION STATEMENT IN 
' PROG1 '. 

Type NEW and this program: 

Sample Program 2 

10 REM THIS PROGRAM DEMONSTRATES CHAINING 
USING THE MERGE AND ALL OPTIONS. 

20 A$="MAINPROG" 

30 CHAIN MERGE "OVRLAY1"* 1000* ALL 

40 END 

Save this program as “MAINPROG”, using the ‘A’ option. Enter NEW, 
then type: 

1000 PRINT A**” HAS CHAINED TO OVRLAY1," 

1010 A$="OVRLAY1" 

1020 B$="0VRLAY2" 

1030 CHAIN MERGE "0VRLAY2"* 1000* ALL * DELETE 
1020-1040 
1040 END 
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Save this program as “OVRLAY1”, using the ‘A’ option. Enter NEW, 
then type: 

1000 PRINT A$5 " HAS CHAINED TO " ;B$;” 

1010 END 

Save this program as “OVRLAY2”, using the ‘A’ option. Load 
MAIN PROG and run it. Your screen should display: 

MAINPROG HAS CHAINED TO 0URLAY1, 

0URLAY1 HAS CHAINED TO 0URLAY2. 

NOTE 

The CHAIN statement with the MERGE option leaves the files 
open and preserves the current OPTION BASE setting. 

If the MERGE option is omitted, CHAIN does not preserve 
variable types or user-defined functions for use by the chained 
program T hat is, any DEFINT, DEFSNG, DEFDBL, DEFSTR, or 
DEF FN statements containing shared variables must be restated 
in the chained program. 

When using the MERGE option, user-defined functions should be 
placed before any CHAIN MERGE statements in the program. 
Otherwise, the user-defined functions will be undefined after the 
merge is complete. 



CHR$ 


CHRS(code) 


Function 


Returns the character corresponding to an ASCII or control code. 

This is the inverse of the ASC function. CHR$ is commonly used to 
send a special character to the display. 

Examples 

PRINT CHR$(35) 

prints the character corresponding to ASCII code 35 (the character 
is #). 
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w 

PRINT CHR*<16) 

puts the display into its black-on-white mode, also called reverse 
video mode. PRINT CHR$(28) returns it to white-on-black and 
converts all reverse video characters into graphics characters. See 
Appendix C for more information. 

Sample Program 

The following program lets you investigate the effect of printing codes 
32 through 255 on the display. (Codes 0-31 represent certain control 
functions.) 

100 CLS 

110 INPUT "TYPE IN THE CODE (32-255)"? C 
120 PRINT CHR$(C)5 
130 GOTO 110 

For a complete list and discussion of output to the video display, see 
the Character Codes table in Appendix C. 


CINT 


W 


CINT(num£>er) 


Function 


Converts number to integer representation. 

CINT rounds the fractional portion of number to make it an integer. 

For example, PRINT CINT(1.5) returns 2; PRINT CINT(-1.5) returns 
- 2. The result is a two-byte integer. 

Sample Program 

PRINT CI NT(17.G5) 

18 

Ready 


W 
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CLEAR 




CLEAR [.memory location ] [,stack space ] 


Statement 


Clears the value of all variables and CLOSES all open files. 

Memory location must be an integer. It specifies the highest memory 
location available for BASIC. The default is the current top of memory 
(as specified when BASIC was loaded or by the location of HIGH$). 
This option is useful if you will be loading a machine-language 
subroutine, since it prevents BASIC from using that memory area. 

Stack space must also be an integer. This sets aside memory for 
temporarily storing internal data and addresses during subroutine calls 
and during FOR/NEXT loops. The default is 512 bytes or one-eighth 
of the memory available, whichever is smaller. An “Out of memory’’ 
error occurs if there is insufficient stack space for program execution. 

NOTE: BASIC allocates string space dynamically. An “Out of string 
space” error occurs only if no free memory is left for BASIC. 

Since CLEAR initializes all variables, you must use it near the 
beginning of your program, before any variables have been defined 
and before any DEF statements. 

Examples: 

CLEAR 

clears all variables and closes all files. 

CLEAR > 45000 

clears all variables and closes all files; makes 45000 the highest 
address BASIC may use to run your programs. 

CLEAR t 61000 * 200 

clears all variables and closes all files; makes 61000 the highest 
address BASIC may use to run your programs, and allocates 200 
bytes for stack space. 
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CLOSE 


CLOSE [buffer,...] 


Statement 


Closes access to a file. 

Buffer is a number from 1-15 used to OPEN the file. If no buffers 
are specified, BASIC closes all open files. 

This command terminates access to a file through the specified 
buffer. If a buffer was not assigned in a previous OPEN statement, 
then 



CLOSE buffer 
has no effect. 

Do not remove a diskette which contains an open file. CLOSE the file 
first. This is because the last records may not have been written to 
disk yet. Closing the file writes the data, if it hasn’t already been 
written. 

See also OPEN and the chapter on ‘Disk Files’. 

Examples 

CLOSE 1» 2» 8 

terminates the file assignments to buffers 1,2, and 8. These buffers 
can now be assigned to other files with OPEN statements. 

CLOSE FIRST* + COUNT* 

• terminates the file assignment to the buffer specified by the sum 
FIRST% + COUNT%. 
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CLS 



CLS 


Statement 


COMMON 


Clears the screen. 

CLS fills the display with blanks and moves the cursor to the 
upper-left corner. Alphanumeric characters and graphics blocks are 
wiped out. 

Sample Program 

540 CLS 

550 FDR I = 1 TO 24 
5G0 PRINT STRING* <7St33> 

570 NEXT I 
580 GOTO 540 



COMMON variable,... 


Statement 


Reserves space for variables so they can be passed to a CHAINed 
program. 

COMMON may appear anywhere in a program, but we recommend 
using it at the beginning. 

The same variable cannot appear in more than one COMMON 
statement. To specify array variables, append “( )” to the variable 
name. If all variables are to be passed, use CHAIN with the ALL 
option and omit the COMMON statement. 

NOTE: array variables used in a COMMON statement must have 
been declared in a DIM statement. 



2-76 






Example 


90 DIM D(50) 

100 COMMON A * B , C » D<)>G$ 
110 CHAIN "PR0G3"» 10 


line 100 passes variables A, B, C, D and G$ to the CHAIN command 
in line 110. 


See also CHAIN. 


CONT 


CONT 


Statement 




Resumes program execution. 

You may only use CONT if the program was stopped by the (BREAK) 
key, a STOP or an END statement in the program. 

CONT is primarily a debugging tool. During a break or stop in 
execution, you may examine variable values (using PRINT) or change 
these values. Then type CONT (ENTER) : execution continues with the 
current variable values. 

You cannot use CONT after editing your program lines or otherwise 
changing your program. CONT is also invalid after execution has 
ended normally. 

Example 

10 INPUT A t 6. C 
20 K=A A 2 
30 LsB^/ .26 
40 STOP 

50 M=C+40*K+100: PRINT M 

Run this program, (to enter the A , press (CLEAR) CD). You will be 
prompted with: 

? 

Type: 

l » 2 » 3 (ENTER) 
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r-\ 

The computer displays: 

Break in 40 

You can now type any immediate command. 

For example: 

PRINT L 

displays 30.7692. You can also change the value of A, B, or C. 

For example: 

c = 4 

changes the value of C in the program. Type: 

CONT 

your screen displays: 144. 

See also STOP. 


COS 




COS (number) 


Function 


Computes the cosine of number. 

COS returns the cosine of number in radians. The number must be 
given in radians. When number is in degrees, use COS{number * 
.01745329). 

The result is always single precision. 

Examples 

Y = C0S(X * .01745329) 
stores in Y the cosine of X, if X is an angle in degrees. 

PRINT COS(5.8) - COS(85 * .42) 
prints the arithmetic (not trigonometric) difference of the two cosines. 
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CSNG 


CSNG (number) 


Function 


Converts number to single precision. 

If number is double precision, when its single-precision value is 
printed, only six significant digits are shown. BASIC rounds the 
number in this conversion. 

Example 

PRINT CSNG<.1453885509) 


prints .145389 

Sample Program 

280 U* = 878.2345878* 

290 PRINT U*5 CSNG<0*) 

RUN 

878.2345878000001 876.235 

Ready 
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CVD, CVI. CVS 


.-'“N 


Function 

CVD(eight-byte string) 

CVS(four-byte string) 

CW\{two-byte string) 


Convert string values to numeric values. 

These functions let you restore data to numeric form after it is read 
from disk. Typically, the data has been read by a GET statement, and 
is stored in a direct access file buffer. 

CVD converts an eight-byte string to a double-precision number. CVS 
converts a four-byte string to a single-precision number. CVI converts 
a two-byte string to an integer. 

CVD, CVI, and CVS are the inverses of MKD$, MKI$, and MKS$, 
respectively. 

Examples 

Suppose the name GROSSPAY$ references an eight-byte field in a 
direct-access file buffer, and after GETting a record, GROSSPAY$ 
contains an MKD$ representation of the number 13123.38. Then the 
statement 

A# = COD(GROSSPAY$) 

assigns the numeric value 13123.38 to the double-precision variable 
A#. 

Sample Program 

This program reads from the file “TEST/DAT”, which is assumed to 
have been previously created. For the program that creates the file, 
see MKD$, MKI$, and MKS$. 

1420 OPEN "D" , It "TEST/DAT"> 14 

1430 FIELD 1 » 2 AS 11$. 4 AS 12$. 8 AS 13$ 

1440 GET 1 

1450 PRINT 001(11$). COS(12$) . C0D(I3$) 

1460 CLOSE 

NOTE: GET without a record number tells BASIC to get the first 
record from the file, or the record following the last record accessed. 
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DATA 


DATA constant,... 


Statement 





Stores numeric and string constants to be accessed by a READ 
statement. 

This statement may contain as many constants (separated by 
commas) as will fit on a line. Each will be read sequentially, starting 
with the first constant in the first DATA statement, and ending with the 
last item in the last DATA statement. 

Numeric expressions are not allowed in a DATA list. If your string 
values include leading blanks, colons, or commas, you must enclose 
these values in double quotation marks. 

DATA statements may appear anywhere it is convenient in a 
program. The data types in a DATA statement must match up with 
the variable types in the corresponding READ statement, otherwise a 
“Syntax error” occurs. 

Examples 

1340 DATA NEW YORK# CHICAGO# LOS ANGELES# 
PHILADELPHIA# DETROIT 

stores five string data items. Note that quote marks aren’t needed, 
since the strings contain no delimiters and the leading blanks are not 
significant. 

1350 DATA 2.72# 3.14153# 0.0174533# 57.29578 

stores four numeric data items. 

1360 DATA "SMITH# T.H."# 38# "THORN# J.R."> 41 

stores both types of constants. Quote marks are required around the 
first and third items because they contain commas (commas are 
delimiters within data fields). 

Sample Program 

NEW 

10 PRINT "CITY"# "STATE"# "ZIP" 

20 READ C*#S$#Z 

30 DATA "DENVER#"# COLORADO# 80211 
40 PRINT C$ »S$ #2 

This program READS string and numeric data from the DATA 
statement in line 30. 
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DATES 



DATES 


Function 


Returns today’s date. 

The operator sets the date when TRSDOS is started up. 

(This system supports dates between January 1, 1980 and December 
31, 1987). 

During a program, if you request the date, BASIC displays it in this 
fashion: 


03/12/83 

Sample Program 

1030 PRINT "Inventory Check:" 

1100 IF DATE$ = "01/31/80" THEN PRINT "Today is 
the last day of January 1980* Time to 
perform monthly inventory*": END 


rOi 
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DEFDBL/INT/SNG/STR 


Statement 

DEFDBL letter,... 

DEFINT letter ,... 

DEFSNG letter,... 

DEFSTR letter,... 


Defines any variables beginning with letter(s) as: (DBL) double 
precision, (INT) integer, (SNG) single precision, or (STR) string. 

NOTE: A type declaration character always takes precedence over a 
DEF statement. 

Examples 

10 DEFDBL L-P 

classifies all variables beginning with the letters L through P as 
double-precision variables. Their values include 17 digits of precision, 
though only 16 are printed out. 

10 DEFSTR A 

classifies all variables beginning with the letter A as string variables. 
10 DEFINT I -N > W»Z 

classifies all variables beginning with the letters I through N, W and Z 
as integer variables. Their values are in the range -32768 to 32767. 

10 DEFSNG I> 0-T 

classifies all variables beginning with the letters I or Q through T as 
single-precision variables. Their values include seven digits of 
precision, though only six are printed out. 





DEF FN 




Statement 

DEF FN function name [(argument ,...)] = function definition 


Defines function name according to your function definition. 

Function name must be a valid variable name. The type of variable 
used determines the type of value the function will return. For 
example, if you use a single-precision variable, the function will 
always return single-precision values. 

Argument represents those variables in function definition that are to 
be replaced when the function is called. If you enter several variables, 
separate them by commas. 

Function definition is an expression that performs the operation of the 
function. A variable used in a function definition may or may not 
appear in argument. If it does, BASIC uses its value to perform the 
function. Otherwise, it uses the current value of the variable. 

Once you define and name a function (by using this statement), you 
can call it and BASIC performs the associated operations. 

Examples 

DEF FNR = RND(90)+9 

defines a function FNR to return a random value between 10 and 99. 
Notice that the function can be defined with no arguments. 

210 DEF FNW# (A# »B#)=(A#-B#)*(A#-B#) 

280 T = FNW#(I#*J#) 

defines function FNW# in line 210. Line 280 calls that function and 
replaces parameters A# and B# with parameters I# and J#. (We 
assume that I# and J# were assigned values elsewhere in the 
program). 

NOTE: Using a variable as a parameter in a DEF FN statement has 
no effect on the value of that variable. You may use that variable in 
another part of the program without interference from DEF FN. 
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Statement 


* 

DEF USR 


DEF USR[d/g/f] =address 


Defines the starting address for the assembly-language subroutine 
identified by digit. 

A program may contain any number of DEF USR statements, allowing 
access to as many subroutines as necessary. However, only 10 
definitions may be in effect at one time. 

If you omit digit, BASIC assumes USR0. 

See also USR, VARPTR and CALL. 

Examples 


DEF USR3 = 8.H7D00 


assigns the starting address 7D00 hexadecimal, 32000 decimal, to the 
USR3 call. When your program calls USR3, control branches to your 
subroutine beginning at 7D00. 


DEF USR = (BASE + IS) 


assigns the starting address 


of BASE + 16 to the USR0 subroutine. 
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DELETE 


DELETE linel - Iine2 


Statement 


Deletes from linel through Iine2 of a program in memory. 

A period can be substituted for either linel or Iine2 to indicate 
the current line number. 

Examples 

DELETE 70 

deletes line 70 from memory. If there is no line 70, an error will occur. 
DELETE 50-110 

deletes lines 50 through 110 inclusive. 

DELETE -40 

deletes all program lines up to and including line 40. 

DELETE -. 

deletes all program lines up to and including the line that has just 
been entered or edited. 

DELETE . 

deletes the program line that has just been entered or edited. 
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Statement 


DIM 


DIM array ( dimensions )), array ( dimensions )),... 



Sets aside storage for arrays with the dimensions you specify. 

Arrays may be of any type: string, integer, single precision or double 
precision, depending on the type of variable used to name the array. 
If no type is specified, the array is classified as single precision. 

When you create the array, BASIC reserves space in memory for 
each element of the array. All elements in a newly- created array are 
set to zero (numeric arrays) or the null string (string arrays). 

NOTE: The lowest element in a dimension is always zero, unless 
OPTION BASE 1 has been used. 

Arrays can be created implicitly, without explicit DIM statements. 
Simply refer to the desired array in a BASIC statement. For example, 

A(5) = 300 

creates array A and assigns element A(5) the value of 300. Each 
dimension of an implicitly-defined array is 11 elements deep, 
subscripts 0-10. 

Examples 

DIM AR(100) 


sets up a one-dimensional array AR( ), containing 101 elements: 
AR(0), AR(1), AR(2), .... AR(98), AR(99), and AR(100). 


NOTE: The array AR( ) is completely independent of the variables 
AR. 



DIM L11(8 >25) 

sets up a two-dimensional array L1%(,), containing 9 x 26 integer 

elements, L1%(0,0), L1%(1,0), L1%(2,0).L1%(8,0), 

LI %(0,1), LI %(1,1).LI %(8,1),. . . ,L1%(0,25), L1%(1,25), 

L1%(8,25). 

Two-dimensional arrays like AR(,) can be thought of as a table in 
which the first subscript specifies a row position, and the second 
subscript specifies a column position: 
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m 


0 *0 

0 * 1 

0 *2 

0 ,3 

♦ ♦ ♦ 

0 123 

0 fZa 

0 *25 

1 >0 

« 

1 tl 

1 »2 

1 *3 

♦ ♦ « 

1 *23 

i ,2a 

1 *25 

« 

1 

7 *0 

7 * 1 

7 ,2 

7 ,3 

♦ * * 

7 *23 

7 *za 

7 *25 

8 ,0 

8 1 1 

8 ,2 

8 *3 

♦ ♦ ♦ 

8 *23 

8 *za 

8 *25 


DIM B 1 ( 2 *5 *8 ) > CR ( 2 *5 >8 ) » LY*<50*2> 

sets up three arrays: 

B1(„) and CR (,,) are three-dimensional, each containing 3*6*9 
elements. 

LY(,) is two-dimensional, containing 51*3 string elements. 


EDIT 


EDIT line 


Statement 


Enters the edit mode so that you can edit line. 

See the chapter on the “Edit Mode” for more information. 

Examples 

EDIT 100 

enters edit mode at line 100. 
edit . 

enters edit mode at current line. 
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END 


END 


Statement 



Ends execution of a program. 

This statement may be placed anywhere in the program. It forces 
execution to end at some point other than the last sequential line. 

An END statement at the end of a program is optional. 

Sample Program 


40 INPUT SI t S2 
50 GDSUB 100 
55 PRINT H 
G0 END 

100 H = SQR(S1*S1 + S2*S2) 
110 RETURN 


line 60 prevents program control from “crashing” into the subroutine. 
Line 100 may only be accessed by a branching statement, such as 
GOSUB in line 50. 
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Function 


EOF {buffer) 


Detects the end of a file. 


This function checks to see whether all characters up to the 
end-of-file marker have been accessed, so you can avoid “Input past 
end” errors during sequential input. 

EOF(buffer) returns 0 (false) when the EOF record has not been read 
yet, and -1 (true) when it has been read. The buffer number must 
access an open file. 

Sample Program 

The following sequence of lines reads numeric data from DATA/TXT 
into the array A( ). When the last data character in the file is read, 
the EOF test in line 30 “passes”, so the program branches out of the 
disk access loop. 



1470 DIM A<100) 'ASSUMING THIS IS A SAFE VALUE 
1480 OPEN "I"* It "DATA/TXT" 

1490 IX = 0 

1500 IF EOF(1) THEN GOTO 1540 
1510 INPUT*1* A<IX) 

1520 I X = IX + 1 
1530 GOTO 1500 

1540 REM PROG. CONT. HERE AFTER DISK INPUT 





ERASE 


ERASE array,... 


Statement 



Erases one or more arrays from a program. 

This lets you to either redimension arrays or use their previously 
allocated space in memory for other purposes. 

If one of the parameters of ERASE is a variable name which is not 
used in the program, an “Illegal Function Call” occurs. 

Example 

450 ERASE C.F 
4B0 DIM F(99) 

line 450 erases arrays C and F. Line 460 redimensions array F. 
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Statement 


ERL 


Returns the line in which an error has occurred. 

This function is primarily used inside an error-handling routine. If no 
error has occurred when ERL is called, line number 0 is returned. 
Otherwise, ERL returns the line number in which the error occurred. If 
the error occurred in the command mode, 65535 (the largest number 
representable in two bytes) is returned. 

Examples 

PRINT ERL 

prints the line number of the error. 

E = ERL 

stores the error’s line number for future use. 

For an example of how to use ERL in a program, see ERROR. 





ERR 


ERR 


Statement 


w 

ERRS$ 


Returns the error code (if an error has occurred). 

ERR is only meaningful inside an error-handling routine accessed by 
ON ERROR GOTO. See Appendix D for a list of Error Codes. 

Example 

IF ERR = 7 THEN 1000 ELSE 2000 

branches the program to line 1000 if the error is an “Out of Memory” 
error (code 7); if it is any other error, control goes instead to line 
2000 . 

For an example of how to use ERR in a program, see ERROR. 


ERRS$ 


Function 


Returns a system error number and message. 

This function returns the number and description of the TRSDOS 
error that caused the latest BASIC disk-related error. If no TRSDOS 
error has occurred, ERRS$ returns a null string. 

Example 

PRINT "THE LATEST TRSDOS ERROR IS "5 ERRS$ 
prints the latest error number message. 
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ERROR 



ERROR code 


Statement 


Simulates a specified error during program execution. 

Code is an integer expressibn in the range 0 to 255 specifying one of 
BASIC’s error codes. 

This statement is mainly used for testing an ON ERROR GOTO 
routine. When the computer encounters an ERROR code statement, it 
proceeds as if the error corresponding to that code had occurred. 
(Refer to Appendix D for a listing of Error Codes and their meanings). 

Example 

ERROR 1 

a “Next Without For” error (code 1) “occurs” when BASIC reaches 
this line. 

Sample Program 

110 ON ERROR GOTO 400 
120 INPUT "WHAT IS YOUR BET"5 B 
130 IF B>5000 THEN ERROR 21 ELSE GOTO 420 
400 IF ERR = 21 THEN PRINT "HOUSE LIMIT IS 
$5000" 

410 IF ERL = 130 THEN RESUME 500 
420 S = S+B 
430 GOTO 120 

500 PRINT "THE TOTAL AMOUNT OF YOUR BET IS"!S 
510 END 

This program receives and totals bets until one of them exceeds the 
house limit. 
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Function 


EXP 


EXP(number) 



Calculates the natural exponent of number. 

Returns e (base of natural logarithms) to the power of number. This is 
the inverse of the LOG function; therefore, number = 

EXP(LOG (number)). The number you supply must be less than or 
equal to 87.3365. 

The result is always single precision. 

Example 

PRINT EXP(-2) 

prints the exponential value .135335. 

Sample Program 

310 INPUT "NUMBER"i N 

320 PRINT "E RAISED TO THE N POWER IS" EXP(N) 
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Statement 


FIELD buffer, length AS field name,... 


Divides a direct-access buffer into one or more fields. Each field is 
identified by field name and is the length you specify. 

Field name must be a string variable. 

This divides a direct file buffer so that you can send data from 
memory to disk and disk to memory. FIELD must be run prior to GET 
or PUT. 

Before “fielding” a buffer, use an OPEN statement to assign that 
buffer to a particular disk file. (The direct access mode, i.e., OPEN 
“D”,... must be used.) The sum of all field lengths should equal the 
record length assigned when the file was OPENed. 

You may use the FIELD statement any number of times to “re-field” a 
file buffer. “Fielding” a buffer does not clear the buffer’s contents; only 
the means of accessing it. Also, two or more field names can 
reference the same area of the buffer. 

See also the chapter on “Disk Files”, OPEN, CLOSE, PUT, GET, 
LSET, and RSET. 

Example 

FIELD 3* 128 AS A$* 128 AS B$ 

tells BASIC to assign two 128-byte fields to the variables A$ and B$. 

If you now print A$ or B$, you will see the contents of the field. Of 
course, this value would be meaningless unless you have previously 
used GET to read a 256-byte record from disk. 

NOTE: All data — both strings and numbers — must be placed into 
the buffer in string form. There are three pairs of functions (MKI$/CVI, 
MKS$/CVS, and MKD$/CVD) for converting numbers to strings and 
strings to numbers. 

FIELD 3 i IB AS NM$ » 25 AS AD$ > 10 AS CY$» 2 AS 
ST$> 7 AS ZP$ 

assigns the first 16 bytes of buffer 3 to field NM$; the next 25 bytes to 
AD$; the next 10 to CY$; the next 2 to ST$; and the next 7 to ZP$. 





FIX 


Function 

FlX(number) 


Returns the truncated integer of number. 

All digits to the right of the decimal point are simply chopped off, so 
the resultant value is a whole number. For a negative, non-whole 
number X, FIX(X) = INT(X) + 1. For all others, FIX(X) = INT(X). 

The result is the same precision as the argument (except for the 
fractional portion). 

Examples 

PRINT FIX (2.6) 
prints 2. 

PRINT FIX(-2.6) 

prints -2. 
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FOR/NEXT 


Statement 

FOR variable = initial value TO final value [STEP increment ] 
NEXT [variable] 


Establishes a program loop. 

A loop allows for a series of program statements to be executed over 
and over a specified number of times. 

BASIC executes the program lines following the FOR statement until 
it encounters a NEXT. At this point, it increases variable by STEP 
increment. If the value of variable is less than or equal to final value, 
BASIC branches back to the line after FOR, and repeats the process. 
If variable is greater than final value, it completes the loop and 
continues with the statement after NEXT. 

If increment has a negative value, then the final value of variable is 
actually lower than the initial value. BASIC always sets the final value 
for the loop variable before setting the initial value. 

NOTE: BASIC skips the body of the loop if initial value times the sign 
of STEP increment exceeds final value times the sign of STEP 
increment. 

Example 

20 FOR H=1 TO 2 STEP -2 
30 PRINT H 
40 NEXT H 

the initial value of H times the sign of STEP increment is greater than 
the final value of H times the sign of STEP increment, therefore 
BASIC skips the body of the loop. (The sign of STEP increment is 
negative in this case.) 

Sample Program 


820 

1=5 

830 

FOR I 

840 

PRINT 

850 

NEXT 

RUN 
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this loop is executed ten times. It produces the following output: 
12345G789 10 

Nested Loops 

FOR/NEXT loops may be “nested”. That is, a FOR ... NEXT loop 
may be placed within the context of another FOR ... NEXT loop. 

The NEXT statement for the inside loop must appear before the 
NEXT for the outside loop. If nested loops have the same end point, a 
single NEXT statement may be used for all of them. 


Sample Program 


880 

FOR I = 1 TO 

3 

880 

PRINT "OUTER 

LOOP" 

800 

FOR J = 1 TO 

2 

810 

PRINT "INNER 

LOOP" 

820 

NEXT J 


830 

NEXT I 



This program performs three “outer loops” and within each, two 
“inner loops”. 

The NEXT statement can be used to close nested loops by listing the 
counter variables (but make sure not to type the variables out of 
order). For example, delete line 920 and change 930 to: 

NEXT J> I 

NOTE: In nested loops, if the variable(s) in the NEXT statement is 
omitted, the NEXT statement matches the most recent FOR 
statement. 




FRE 


FRE (dummy number) or (dummy string) 


Function 


Returns the number of bytes in memory not being used by BASIC. 

NOTE: FRE forces a “garbage collection” before returning the number 
of free bytes. This may take up to one and a half minutes. Using FRE 
periodically results in shorter delays for each garbage collection. 

Examples 

PRINT FRE("44" ) 
prints the amount of memory left. 

PRINT FRE(44) 
prints the amount of memory left. 


GET 


GET buffer [.record] 


Statement 


Gets a record from a direct-access disk file and places it in a buffer. 

Before using GET, you must OPEN the file and assign it a buffer. 

When BASIC encounters GET, it reads the record number from the 
file and places it into the buffer. The actual number of bytes read 
equals the record length set when the file is OPENed. 

If record is omitted, BASIC gets the next record (after the last GET) 
and reads it into the buffer. 


D 


n 







Examples 

GET 1 

gets the next record into buffer 1. 
GET 1» 25 

gets record 25 into buffer 1. 


GOSUB 


GOSUB line 


Statement 


Goes to a subroutine, beginning at line. 

You can call subroutine as many times as you want. When the 
computer encounters RETURN in the subroutine, it returns control to 
the statement which follows GOSUB. 


GOSUB is similar to GOTO in that it may be preceded by a test 
statement. Every subroutine must end with a RETURN. 

Example 

GOSUB 1000 

branches control to the subroutine at 1000. 


Sample Program 


260 GOSUB 280 

270 PRINT "BACK FROM SUBROUTINE": END 
280 PRINT "EXECUTING THE SUBROUTINE" 
290 RETURN 


transfers 
Line 290 
following 


control from line 260 to the subroutine beginning at line 280. 
instructs the computer to return to the statement immediately 
GOSUB. 
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GOTO 




GOTO line 


Statement 


Goes to the specified line. 

When used alone, GOTO line results in an unconditional (automatic) 
branch. However, test statements may precede the GOTO to effect a 
conditional branch. 

You can use GOTO in the command mode as an alternative to RUN. 
This lets you pass values assigned in the command mode to 
variables in the execute mode. 

Example 

GOTO 100 

transfers control automatically to line 100. 

Sample Program 

10 READ R 

20 IF R = 13 THEN END 

30 PRINT "R ="5R 

40 A=3.14*R‘2 

50 PRINT "AREA ="5A 

60 GOTO 10 

70 DATA 5 »7 > 12 > 13 

RUN 

line 10 reads each of the data items in line 60; line 50 returns 
program control to line 10. This enables BASIC to calculate the area 
for each of the data items, until it reaches item 13. 

NOTE: To enter the * symbol, press (CLEAR) CD. 
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Function 


-—■ 

HEX$ 


HEX$(number) 



Calculates the hexadecimal value of number. 

HEX$ returns a string which represents the hexadecimal value of the 
argument. The value returned is like any other string: it cannot be 
used in a numeric expression .That is, you cannot add hex strings. 
You can concatenate them, though. 

Examples 

PRINT HEX$(30)t HEX$(50)* HEX$(9fl) 
prints the following strings: 

IE 32 5A 

Y$ = HEX$(X/16) 

Y$ is the hexadecimal string representing the integer quotient X/16. 


IF . . . THEN . . . ELSE 


Statement 

IF expression THEN statement(s) or line 
[ELSE statements)] or [line] 



Tests a conditional expression and makes a decision regarding 
program flow. 

If expression is true, control proceeds to the THEN statement or line. 
If not, control jumps to the matching ELSE statement, line, or down to 
the next program line. 
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Examples 

IF X > 127 THEN PRINT "OUT OF RANGE" : END 

passes control to PRINT, then to END if X is greater than 127. If X is 
not greater than 127, control jumps down to the next line in the 
program, skipping the PRINT and END statements. 

If ft < B THEN PRINT "A < B" ELSE PRINT "B < A" 

tests the first expression, if true, prints “A < B”. Otherwise, the 
program jumps to the ELSE statement and prints “B < A”. 

IF X > 0 AND Y <> 0 THEN Y = X + 180 

assigns the value X + 180 to Y if both expressions are true. 
Otherwise, control passes directly to the next program line, skipping 
the THEN clause. 

IF A$ = "YES" THEN 210 ELSE IF A* = "NO" THEN 
400 ELSE 370 

branches to line 210 if A$ is YES. If not, the program skips over to 
the first ELSE, which introduces a new test. If A$ is NO, then the 
program branches to line 400. If A$ is any value besides NO or YES, 
the program branches to line 370. 

Sample Program 

IF THEN ELSE statements may be nested. However, you must take 
care to match up the IFs and ELSEs. (If the statement does not 
contain the same number of ELSE’s and IPs, each ELSE is matched 
with the closest unmatched IF.) 

1040 INPUT "ENTER TWO NUMBERS"! A» B 
1050 IF A <= B THEN IF A < B THEN PRINT A! 

ELSE PRINT "NEITHER"! ELSE PRINT B! 

10G0 PRINT "IS SMALLER THAN THE OTHER" 

This program prints the relationship between the two numbers 
entered. 
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INKEY$ 


1NKEY$ 


Function 



Returns a keyboard character. 

Returns a one-character string from the keyboard without having to 
press (ENTER) . If no key is pressed, a null string (length zero) is 
returned. Characters typed to 1NKEY$ are not echoed to the display. 

!NKEY$ is invariably put inside some sort of loop. Otherwise a 
program execution would pass through the line containing INKEY$ 
before a key could be pressed. 

Example 

10 A$ = INKEY$ 

20 IF A$ = THEN 10 

This causes the program to wait for a key to be pressed. 


INP 


m?(port) 


Function 



Returns the byte read from a port. 

INP is the complementary function of the OUT statement. 

Port may be any integer from 0 to 255. For information on Model 4’s 
assigned ports, see the Technical Reference Manual. 

Example 

100 A=INP(255) 
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INPUT 


Statement 

INPUT[;] [“prompt string”-,] variable!, variable2,... 


Inputs data from the keyboard into one or more variables. 

When BASIC encounters this statement, it stops execution and 
displays a question mark. This means that the program is waiting for 
you to type data. 

INPUT may specify a list of string or numeric variables, indicating 
string or numeric data items to be input. For instance, INPUT X$, XI, 
Z$, Z1 calls for you to input a string literal, a number, another string 
literal, and another number, in that order. 

The number of data items you supply must be the same as the 
number of variables specified. You must separate data items by 
commas. 

Responding to INPUT with too many items, or with the wrong type of 
value (including numeric type), causes BASIC to print the message 
“?Redo from start”. No values are assigned until you provide an 
acceptable response. 

If a prompt string is included, BASIC prints it, followed by a question 
mark. This helps the person inputting the data to enter it correctly. If 
instead of a semicolon, you type a comma after prompt string, BASIC 
suppresses the question mark when printing the prompt. Prompt 
string must be enclosed in quotes. It must be typed immediately after 
INPUT. 

If INPUT is immediately followed by a semicolon, any carriage returns 
pressed as part of the response are not echoed. 

Examples 

INPUT Y2 

when BASIC reaches this line, you must type any number and press 
(ENTER) before the program will continue. 

INPUT SENTENCE* 

when BASIC reaches this line, you must type in a string. The string 
wouldn’t have to be enclosed in quotation marks unless it contained a 
comma, a colon, or a leading blank. 
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INPUT "ENTER YOUR NAME AND AGE (NAME * AGE)"5 
N$ » A 

would print a message on the screen which would help the person at 
the keyboard to enter the right kind of data. 

Sample Program 

50 INPUT "HOW MUCH DO YOU WEIGH"? X 
60 PRINT "ON MARS YOU WOULD WEIGH ABOUT" 

CINT(X * .38) "POUNDS." 


INPUT# 


INPUT# buffer, variable,... 


Statement 


Inputs data from a sequential disk file and stores it in a program 
variable. 

Buffer is the number used when the file was OPENed for input. 

Variable contains the variable name(s) that will be assigned to the 
item(s) in the file. 

With INPUT#, data is input sequentially. That is, when the file is 
OPENed, a pointer is set to the beginning of the file. The pointer 
advances each time data is input. To start reading from the beginning 
of the file again, you must close the file buffer and re-OPEN it. 

INPUT# doesn’t care how the data was placed on the disk — 
whether a single PRINT# statement put it there, or whether it 
required ten different PRINT# statements. What matters to INPUT# is 
the position of the terminating characters and the EOF marker. 

When inputting data into a variable, BASIC ignores leading blanks. 
When the first non-blank character is encountered, BASIC assumes it 
has encountered the beginning of the data item. 

The data item ends when a terminating character is encountered or 
when a terminating condition occurs. The terminating characters vary, 
depending on whether BASIC is inputting to a numeric or string 
variable. 
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Numeric values: BASIC begins input at the first character which is 
neither a space nor a carriage return. It ends input when it encounters 
a space, carriage return, or a comma. 


String values: BASIC begins input with the first character which is 
neither a space nor carriage return. It ends input when it encounters a 
carriage return or comma. One exception to this rule: If the first 
character is a quotation mark( ”), the string will consist of all 
characters between the first quotation mark and the second. Thus, a 
quoted string may not contain a quotation mark as a character. 


If the end-of-file is reached when a numeric or string item is being 
INPUT, the item is terminated. 


Examples 


INPUT#1 » A «B 


sequentially inputs two numeric data items from disk and places them 
in A and B. Buffer #1 is used. 


INPUT#4 » A$ * B$ » C$ 

sequentially inputs three string data items from disk and places them 
in A$, B$, and C$. Buffer #4 is used. 


INPUTS 


INPUTS(numberf [, ,number2 ]) 


Statement 


Inputs a string of characters from either the keyboard or a sequential 
disk file. 


Numberl is the number of characters to be input. It must be a value 
in the range 1 to 255. Number2 is a buffer which accesses a 
sequential input file. 


INPUT$(numberf) inputs a string of characters from the keyboard. 
When the program reaches this line, it stops until you (or any 
operator) type numberl characters. 


(You don’t need to press (ENTER) 
to signify end-of-line.) The charact er(s) yo u type are not displayed on 
the screen. Any character, except (BREAK) , is accepted for input. No 
characters are echoed. 
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INPUT$(m;mber7, number2) inputs a string from a sequential disk file. 
Number 2 is the buffer associated with that disk file. 

Examples 

A$ = INPUT $(5) 

assigns a string of five keyboard characters to A$. Program execution 
is halted until the operator types five characters. 

A$ = INPUTS(11.3) 

assigns a string of 11 characters to A$. The characters are read from 
the disk file associated with buffer 3. 

Sample Programs 

This program shows how you could use INPUTS to have an operator 
input a password for accessing a protected file. By using INPUTS, the 
operator can type in the password without anyone seeing it on the 
video display. (To see the full file specification, run the program, then 
type PRINT F$). 

110 LINE INPUT "TYPE IN THE FILESPEC/EXT"i F$ 

120 PRINT "TYPE IN THE PASSWORD -- MUST TYPE 8 
CHARACTERS: "5 
130 P$ = INPUTS(8) 

140 F $ = F $ + + PS 

In the program below, line 100 OPENs a sequential input file (which 
we assume has been previously created). Line 200 retrieves a string 
of 70 characters from the file and stores them in T$. Line 300 
CLOSEs the file. 

100 OPEN "I"» 2 , "TEST/DAT" 

200 TS = INPUTS(70 >2) 

300 CLOSE 
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INSTR ([integer,] stringl, stringZ) 


Function 


Searches for the first occurrence of string2 in stringl, and returns the 
position at which the match is found. 

Integer specifies a position in stringl. If used it must be a value in the 
range 1 to 255. 

This function lets you search through a string to see if it contains 
another string. If it does, INSTR returns the starting position of the 
substring in the target string; otherwise, it returns zero. Note that the 
entire substring must be contained in the search string, or zero is 
returned. 

Optional integer sets the position for starting the search. If omitted, 
INSTR starts searching at the first character in stringl. 

Examples 

In these examples, A$ = “LINCOLN”: 

INSTR(A$ » "INC") 
returns a value of 2. 

INSTR(A$ > "12") 
returns a zero. 

I NSTR(A$ > "LINCOLNABRAHAM") 
returns a zero. For a slightly different use of INSTR, look at: 

INSTR (3 > "1232123"» "12") 
which returns 5. 

Sample Program 

The program below uses INSTR to search through the addresses 
contained in the program’s DATA lines. It counts the number of 
addresses with a specified county zip code (761—) and returns that 






number. The zip code is preceded by an asterisk to distinguish it from 
the other numeric data found in the address. 

3G0 RESTORE 
370 COUNTER = 0 
390 READ ADDRESS* 

395 IF ADDRESS* = " *END" THEN 410 
400 IF INSTR(ADDRESS** "*7G1") <> 0 THEN COUNTER 
COUNTER + 1 ELSE 390 
405 GOTO 390 

410 PRINT "NUMBER OF TARRANT COUNTY, TX 
ADDRESSES IS" COUNTER: END 
420 DATA "5950 GORHAM DRIVE, BURLESON, TX 
*7G148" 

430 DATA "71 FIRSTFIELD ROAD, GAITHERSBURG, MD 
*20760" 

440 DATA "1000 TWO TANDY CENTER, FORT WORTH, 

TX *76102" 

450 DATA "1GG33 SOUTH CENTRAL EXPRESSWAY, 
RICHARDSON, TX *75080" 

4G0 DATA "*END" 



INT 


INT(number) 


Function 



Converts number to integer value. 

This function returns the largest integer which is not greater than the 
number. 

The result has the same precision as the argument except for the 
fractional portion. Number is not limited to the range -32768 to 
32767. 

Examples 

PRINT I NT(79,89) 

prints 79. 

PRINT INT (-12,11) 

prints -13. 
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KILL 



KILL ‘‘filespec" 


Statement 


"Kills” (deletes) filespec from disk. 

You may KILL any type of disk file. However, if the file is currently 
OPEN, a “File already open” error occurs. You must CLOSE the file 
before deleting it. 

Example 

KILL "FILE/BAS" 

deletes this file from the first drive which contains it. 

KILL "DATA:2" 
deletes this file from Drive 2 only. 

LEFTS 


LEFT$(str/ng,/nteger) 


Function 


Returns the leftmost integer characters of string. 

If integer is equal to or greater than LEN (string), the entire string is 
returned. 

Examples: 

PRINT LEFTS("BATTLESHIPS"* 6) 
prints BATTLE. 

PRINT LEFT $("BIG FIERCE DOG"* 20) 

since BIG FIERCE DOG is less than 20 characters long, the whole 
phrase is printed. 


2-112 








Sample Program 

740 A$ = "TIMOTHTY" 

750 B$ = LEFT $(A$» 3) 

7G0 PRINT B$5 "--THAT'S SHORT FOR "5 A$ 

When this is run, BASIC prints: 

TIM--THAT 'S SHORT FOR TIMOTHY 


Line 750 gets the three leftmost characters of A$ and stores them in 
B$. Line 760 prints these three characters, a string, and the original 
contents of A$. 


LEN 


Function 

LEN(sf#7ng) 


Returns the number of characters in string. 

Examples 

X = LEN(SENTENCE*) 

gets the length of SENTENCES and stores it in X. 

PRINT LEN("CAMBRIDGE") + LEN("BERKELEY") 

prints 17. 
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LET 



LET variable = expression 


Statement 


Assigns the value of expression to variable. 

BASIC doesn’t require assignment statements to begin with LET, but 
you might want to use LET to be compatible with versions of BASIC 
that do require it. 

Examples 

LET A$ = "A ROSE IS A ROSE" 

LET B1 = 1.23 
LET X = X - Z1 


In each case, the variable on the left side of the equals sign is 
assigned the value of the constant or expression on the right side. 

Sample Program 

550 P = 1001: PRINT "P =" P 

560 LET P = 2001: PRINT "NOW P = "P 


rs 
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LINE INPUT 


Statement 

LINE INPUT[;][“prompf message”;] string variable 



Inputs an entire line (up to 254 characters) from the keyboard. 

LINE INPUT is a convenient way to input string data without having to 
worry about accidental entry of delimiters (commas, quotation marks, 
etc.). 

LINE INPUT (the space is not optional) is similar to INPUT, except: 

— The computer does not display a question mark when waiting for 
input. 

— Each LINE INPUT statement can assign a value to only one 
variable. 

— Commas and quotes can be used as part of the string input. 

— Leading blanks are not ignored — they become part of variable. 

The only way to terminate the string input is to press (ENTER) . 

However, if LINE INPUT is immediately followed by a semicolon, 
pressing (ENTER) does not echo a carriage return to the display. 

Some situations require that you input commas, quotes, and leading 
blanks as part of the data. LINE INPUT serves well in such cases. 

Examples: 

LINE INPUT A$ 

inputs A$ without displaying any prompt. 

LINE INPUT "LAST NAME t FIRST NAME? "5 N$ 

displays a prompt message and inputs data. Commas do not 
terminate the input string, as they would in an INPUT statement. 

You may abort a LINE INPUT statement by pressing (BREAK) . BASIC 
returns to command level and displays Ready. Typing CONT resumes 
execution at LINE INPUT. 
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LINE INPUT# 



LINE INPUT# buffer, variable 


Statement 


Inputs an entire line of data from a sequential disk file to a string 
variable. 

Buffer is the number under which the file was OPENed. 

This statement is useful when you want to read an ASCII-format 
BASIC program file as data, or when you want to read in data without 
following the usual restrictions regarding leading characters and 
terminators. 

LINE INPUT# reads everything from the first character up to: 

— the end-of-file 

— the 255th data character 

Other characters encountered — quotes, commas, leading blanks — 
are included in the string. 

Example 

If the data on disk looks like this: 

10 CLEAR 500 

20 OPEN "I" * 1 * "PROG" 

then the statement 

LINE INPUT*1* A* 

could be used repetitively to read each program line, one at a time. 
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LIST 


LIST [startline]-[endline] 


Statement 


Lists a program in memory to the display. 

Startline specifies the first line to be listed. If omitted, BASIC starts 
with the first line in your program. 

Endline specifies the last line to be listed. If omitted, BASIC ends with 
the last line in your program. 

You can substitute period (.) for either startline or endline to signify 
current line number. 

Examples 

LIST 

displays the entire program. To stop the automatic scrolling, press 
(SHIFTXCgD . This freezes the display. Press any key to continue the 
listing. 

LIST 50 

displays line 50. 

LIST 50-85 

displays lines in the range 50-85. 

LIST 

displays the program line that has just been entered or edited, and all 
higher-numbered lines. 

LIST -227 

displays all lines up to and including 227. 
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LLIST 



LUST [startline]-\endline ] 


Statement 


Lists program lines in memory to the printer. 

The only difference between LLIST and LIST is that LLIST lists the 
lines on printer. See LIST. 

Examples 

LLIST 

lists the entire program to the printer. To stop this process, press 
dHUD® • This causes a temporary halt in the computer’s output to 
the printer. Press any key to continue printing. 

LLIST G8-90 

prints lines in the range 68-90. 
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LOAD 


LOAD filespec [,R] 


Statement 


Loads filespec, a BASIC program, into memory. 

The R option tells BASIC to run the program. (LOAD with the R 
option is equivalent to the command RUN filespec, R). 

LOAD without the R option wipes out any resident BASIC program, 
clears all variables, and CLOSES all OPEN files. LOAD with the R 
option leaves all OPEN files open and runs the program 
automatically. 

You can use either of these commands inside programs to allow 
program chaining (one program calling another). 

If you attempt to LOAD a non-BASIC file, a “Direct statement in file” 
w error will occur. 

Example 

LOAD "PROG 1/BAS:2" 

loads PROG1/BAS from Drive 2. BASIC then returns to the command 
mode. 

LOAD "PROGl/BAS" 

loads PROGl/BAS since no drive is specified, BASIC begins 
searching for it in Drive 0. 
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LOC 



LOC (buffer) 


Function 


Returns the current record number. 

Buffer is the buffer under which the file was OPENed. 

LOC is used to determine the current record number, that is, the 
number of the last record processed since the file was OPENed. It 
returns the record number accessed by the last GET or PUT 
statement. 

LOC is also valid for sequential files. It returns the number of sections 
(256-byte block:) read from or written to the file since the file was 
OPENed. 

Example 

IF LOC(1)>55 THEN END 

if the current record number is greater than 55, ends program 
execution. 

Sample Program 

1310 A$ = "WILLIAM WILSON" 

1320 GET 1 

1330 IF N$ = A$ THEN PRINT "FOUND IN RECORD" 

LOC(1): CLOSE: END 
1340 GOTO 1320 

This is a portion of a program. Elsewhere the file has been OPENed 
and FIELDed. N$ is a field variable. If N$ matches A$, the record 
number in which it was found is printed. 




2-120 





LOF 


LOF(buffer) 


Function 


Returns the end-of-file record number. 

Buffer is the number under which a file was OPENed. 

This function tells you the number of the last record in a direct-access 
file. 

Example 

Y = LOF(5) 

assigns the last record number to variable Y. 

Sample Programs 

s_/ During direct access to a pre-existing file, you often need a way to 

know when you’ve read the last valid record. LOF provides a way. 

1540 OPEN "R"» It "UNKNOWN/TXT"> 255 
1550 FIELD 1 * 255 AS A$ 

1560 FOR IX = 1 TO LOF(1) 'LOF(l) = HIGHEST 
1570 GET If 1% 'RECORD NUM. TO BE 

1580 PRINT A$ 'ACCESSED 

1590 NEXT 1% 

1S00 CLOSE 

If you attempt to GET record numbers beyond the end-of-file, BASIC 
gives you an error. 

When you want to add to the end of a file, LOF tells you where to 
start adding: 

1600 IX = LOF(1) + 1 'HIGHEST EXISTING RECORD 
1610 PUT 1f IX 'ADD NEXT RECORD 
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LOG 



LOG (number) 


Function 


Computes the natural logarithm of number. 

This is the inverse of the EXP function. The result is always in single 
precision. 

Examples 

PRINT LOGO.14159) 
prints the value 1.14473. 

Z = 10 * LOG(Ps/Pl) 

performs the indicated calculation and assigns the value to Z. 

Sample Program 

This program demonstrates the use of LOG. It utilizes a formula taken 
from space communications research. 

540 INPUT "DISTANCE SIGNAL MUST TRAVEL 
(MILES)"! D 

550 INPUT "SIGNAL FREQUENCY (GIGAHERTZ)"; F 
5S0 L = 9G.58 + (20 * LOG(F)) + (20 * LOG(D)) 

570 PRINT "SIGNAL STRENGTH LOSS IN FREE SPACE 
IS" L "DECIBELS." 
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LPOS 


LPOS (number) 


Function 


Returns the logical position of the line printer’s print head within the 
line printer’s buffer. 

Number is a dummy argument. 

This function does not necessarily give the physical position of the 
print head. 

Example 

100 IF LPOS(X)>G0 THEN LPRINT 

LPRINT, LPRINT USING 

w 


Statement 

LPRINT data,... 

LPRINT USING format; data,... 


Prints data on the printer. 

See PRINT and PRINT USING for more information. 

Examples 

LPRINT (A * 2)/3 

prints the value of expression (A * 2)/3 on the printer. 

LPRINT TAB(50) "TABBED 50" 

moves the line printer carriage to TAB position 50 and prints 
“TABBED 50”. (Refer to the TAB function). 

LPRINT USING "#####,#••; 2.17 

sends the formatted value bbtob2.2 to the line printer. 

W 
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Statement 


LSET field name = data 


Sets data in a direct-access buffer field name. 

Before using LSET, you must have used FIELD to set up buffer fields. 

See also the chapter on “Disk Files”, OPEN, CLOSE, FIELD, GET, 
PUT, and RSET. 

Example 

Suppose NM$ and AD$ have been defined as field names for a direct 
access file buffer. NM$ has a length of 18 characters; AD$ has a 
length of 25 characters. The statements 

LSET NM$ = "JIM CRICKET» JR." 

LSET AD$ = "2000 EAST PECAN ST." 

set the data in the buffer as follows: 

JIMkSCRICKET .JR.kSBH 2000KEASTKPECANKST . KKKKKK 

Notice that filler blanks were placed to the right of the data strings in 
both cases. If we had used RSET statements instead of LSET, the 
filler spaces would have been placed to the left. This is the only 
difference between LSET and RSET. 

If a string item is too large to fit in the specified buffer field, it is 
always truncated on the right. That is, the extra characters on the 
right are ignored. This applies to both LSET and RSET. 





MEM 


w 


MEM 


Function 



Returns the amount of memory. 

MEM performs the same function as FRE. It returns the number of 
unused and unprotected bytes in memory. 

This function may be used in the immediate mode to see how much 
space a resident program occupies. It may also be used inside a 
program to avert “Out of memory” errors. MEM requires no argument. 

Example 

PRINT MEM 

Enter this command in the immediate mode (no line number is 
needed). The number returned indicates the amount of leftover 
memory; that is, memory not being used to store programs, variables, 
strings, the stack, or not reserved for object files. 

Sample Program 

1610 IF MEM < 80 THEN 1630 
1620 DIM A(15) 

1630 REM PROGRAM CONTINUES HERE 

If fewer than 80 bytes of memory are left, control switches to another 
part of the program. Otherwise, an array of 16 elements is created. 
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Statement 


MERGE filespec 


Loads filespec, a BASIC program, and merges it with the program 
currently in memory. 

Filespec specifies a BASIC file in ASCII format (a program saved with 
the A option). If filespec is a constant, it must be enclosed in quotes. 

Program lines in the disk program are inserted into the resident 
program in sequential order. For example, suppose that three of the 
lines from the disk program are numbered 75, 85 and 90, and three of 
the lines from the current program are numbered 70, 80, and 90. 
When MERGE is used on the two programs, this portion of the new 
program will be numbered 70, 75, 80, 85, 90. 

If line numbers on the disk program coincide with line numbers in the 
resident program, the disk program’s lines replace the resident 
program’s lines. 

MERGE closes all files and clears all variables. Upon completion, 
BASIC returns to the command mode. 

Example 

Suppose you have a BASIC program on disk, PROG2/TXT (saved in 
ASCII), which you want to merge with the program you’ve been 
working on in memory. Then we use: 

MERGE 11 PR0G2/TXT 11 

merges the two programs. 

Sample Programs 

MERGE provides a convenient means of putting program modules 
together. For example, an often-used set of BASIC subroutines can 
be tacked onto a variety of programs with this command. 

Suppose the following program is in memory: 







80 REM 
90 REM LINE 
100 REM 
110 REM 
120 REM 
130 END 


MAIN PROGRAM 

NUMBER RESERVED FOR SUBROUTINE HOOK 
PROGRAM LINE 
PROGRAM LINE 
PROGRAM LINE 


And suppose the following subroutine, SUB/TXT, is stored on disk in 
ASCII format: 


90 GOSUB 
1000 REM 
1010 
1020 
1030 
1040 


REM 

REM 

REM 

RETURN 


1000 SUBROUTINE HOOK 

BEGINNING OF SUBROUTINE 
SUBROUTINE LINE 
SUBROUTINE LINE 
SUBROUTINE LINE 


You can MERGE the subroutine with the main program with: 

MERGE "SUB/TXT" 


and the new program in memory is: 


80 

REM 

MAIN PROGRAM 


90 

GOSUB 

1000 SUBROUTINE 

HOOK 

100 

REM 

PROGRAM LINE 


1 10 

REM 

PROGRAM LINE 


120 

REM 

PROGRAM LINE 


130 

END 



1000 

REM 

BEGINNING OF 

SUBROUTINE 

1010 

REM 

SUBROUTINE LINE 

1020 

REM 

SUBROUTINE LINE 

1030 

REM 

SUBROUTINE LINE 

10a0 

RETURN 
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MID$ 


Statement 

M\D$(oldstring, position [,length]) = replacement string 


Replaces a portion of an oldstring with replacement string. 

Oldstring is the variable name of the string you want to change. 

Position is a number specifying the position of the first character to be 
changed. 

Length is a number specifying the number of characters to be 
replaced. 

Replacement string is the string to replace a portion of oldstring. 

The length of the resultant string is always the same as the original 

string. If replacement string is shorter than length, the entire r> 

replacement string is used. 

Examples: 

A$ = "LINCOLN" 

li I D$ < A$ » 3 f 4) = "12345": PRINT A$ 
returns LI1234N. 

MID$ (A$ t 5) = "01": PRINT A$ 
returns LINC01N. 

MID$ <A$, 1* 3) = "***": PRINT A$ 
returns ***COLN. 
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MID$ 


MID$(sfring, integer [ ,number ]) 


Function 


Returns a substring of string, beginning at position integer. 

If integer is greater than the number of characters in string, MID$ 
returns a null string. 

Number is the number of characters in the substring. If omitted, 

BASIC returns all right most characters, beginning with the character 
at position integer. 

Examples 

If A$ = “WEATHERFORD” then 
PRINT MID$(A$» 3* 2) 
prints AT. 

F$ = MID$(A$ > 3) 
puts ATHERFORD into F$. 

Sample Program 

200 INPUT "AREA CODE AND NUMBER 
(NNN-NNN-NNNN)"! PH$ 

210 EX$ = MID$(PH»# 5. 3) 

220 PRINT "NUMBER IS IN THE " EX$ " EXCHANGE." 

The first three digits of a local phone number are sometimes called 
the exchange of the number. This program looks at a complete phone 
number (area code, exchange, last four digits) and picks out the 
exchange of that number. 
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MKD$, MKI$, MKS$ 


4k 


Function 

MKI$(/nteger expression) 

MKS $(single-precislon expression) 

M KD $(double-precision expression) 


Convert numeric values to string values. 

Any numeric value that is placed in a direct file buffer with an LSET or 
RSET statement must be converted to a string. 

These three functions are the inverse of CVD, CVI, and CVS. The 
byte values which make up the number are not changed; only one 
byte, the internal data-type specifier, is changed, so that numeric data 
can be placed in a string variable. 

MKD$ returns an eight-byte string; MKI$ returns a two-byte string; 
and MKS$ returns a four-byte string. 

Example 

LSET AUG$ = MKS$<0.123) 

Sample Program 


1350 

OPEN 

"D" 

t 

1# "TEST/DAT"» 14 

13G0 

FIELD 

1 * 

2 

AS 11$ » 4 AS 12$ » 

1370 

LSET 

11$ 

= 

MKI $(3000) 

1380 

LSET 

12$ 

= 

MKD$(3000 «1) 

1390 

LSET 

13$ 

= 

MKD$<3000,00001) 

1400 

PUT 1 

* 1 



1410 

CLOSE 

1 




For a program that retrieves the data from TEST/DAT, see 
CVD/CVI/CVS. 


✓'-s 
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NAME 


W 

NEW 


NAME old filespec AS new filespec 

Statement 

Renames old filespec as new filespec. 


With this statement, the data in the file is left unchanged. The new 
filespec may not contain a password or drive specification. 

Example 


NAME "FILE" AS "FILE/OLD" 


renames FILE as FILE/OLD. 


NAME B$ AS A$ 


renames B$ as A$. 


NEW 

Statement 


Deletes the program currently in memory and clears all variables. 

NEW displays a new (clear) screen and returns you to the command 
mode. 

Example 

NEW 




2-131 






OCT$ 



OCT $(number) 


Function 


Computes the octal value of number. 

OCT$ returns a string which represents the octal value of number. 
The value returned is like any other string — it cannot be used in a 
numeric expression. 

Examples 

PRINT OCT$(30>, OCT $(50) » OCT$(90) 

prints the following strings: 

36 62 132 

Y$ = OCT $(X/84) 

Y$ is a string representation of the integer quotient X/84 to base 8. 

ON ERROR GOTO 


ON ERROR GOTO line 


Statement 


Transfers control to line if an error occurs. 

This lets your program “recover” from an error and continue 
execution. (Normally, you have a particular type of error in mind when 
you use the ON ERROR GOTO statement). 

ON ERROR GOTO has no effect unless it is executed before the 
error occurs. To disable it, execute an ON ERROR GOTO 0. If you 
use ON ERROR GOTO 0 inside an error-trapping routine, BASIC 
stops execution and prints an error message. 
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The error-handling routine must be terminated by a RESUME 
statement. See RESUME. 

Example 

10 ON ERROR GOTO 1500 

branches program control to line 1500 if an error occurs anywhere 
after line 10. 

For the use of ON ERROR GOTO in a program, see the sample 
program for ERROR. 

ON . . . GOSUB 


ON number GOSUB linel, Iine2,... 


Statement 


Goes to a subroutine at the line specified by the value of number. 

Number must be between 0 and 255, inclusive. For example, if 
number’s value is three, the third line number in the list is the 
destination of the branch. 

If number’s value is zero or greater than the number of items in the 
list (but less than or equal to 255), BASIC continues with the next 
executable statement. If number is negative or greater than 255, an 
“Illegal function call” error occurs. 

Example 

ON Y GOSUB 1000 t 2000» 3000 

if Y = 1, the subroutine beginning at 1000 is called. If Y = 2, the 
subroutine at 2000 is called. If Y = 3, the subroutine at 3000 is 
called. 

Sample Program 


430 

INPUT 

"CHOOSE 1» 

2 t OR 

3 "5 I 

440 

ON I 

GOSUB 500 , 600i 700 

450 

END 




500 

PRINT 

"SUBROUTINE 

#1" : 

RETURN 

600 

PRINT 

"SUBROUTINE 

*2" : 

RETURN 

700 

PRINT 

"SUBROUTINE 

#3" : 

RETURN 
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ON 


GOTO 


ON number GOTO line, line,... 


Statement 


Goes to the line specified by the value of number. 

Number is a numeric expression between 0 and 255. 

This statement is very similar to ON ... GOSUB. However, instead of 
branching to a subroutine, it branches control to another program line. 


The value of number determines to which line the program will 
branch. For example, if the value is four, the fourth line number in the 
list is the destination of the branch. If there is no fourth line number, 
control passes to the next statement in the program. 

If the value of expression is negative or greater than 255, an “Illegal 
function call” error occurs. Any amount of line numbers may be 
included after GOTO. 

Example 

ON MI GOTO 150 > 1G0 * 170f 150» 180 

tells BASIC to “Evaluate Ml, 

if the value of Ml equals one then go to line 150; 

if it equals two, then go to 160; 

if it equals three, then go to 170; 

if it equals four, then go to 150; 

if it equals five, then go to 180; 

if the value of Ml doesn’t equal any of the numbers one through five, 
advance to the next statement in the program”. 
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OPEN 


Statement 

OPEN mode, buffer, filespec [,record length ] 


Opens a disk file. 

Mode is a string expression whose first character is one of the 
following: 

O for sequential output mode 
I for sequential input mode 
E for sequential output and extend mode 
D or R for direct input/output mode 

Buffer is an integer between 1 and 15. It specifies which area in 
memory you will use to access the file. 

Filespec specifies a TRSDOS file. 

Record length is an integer which sets the record length for 
direct-access files. The default is 256 bytes. 

Once you have assigned a buffer to a file with the OPEN statement, 
that buffer cannot be used in another OPEN statement. You must first 
CLOSE the first file. 

Examples 

OPEN "D"» 2 > "DATA/BAS.SPECIAL” 

opens the file DATA/BAS in direct-access mode, with the password 
SPECIAL. Buffer 2 is used. If DATA/BAS does not exist, it is created 
on the first non write-protected drive. The record length is 256 bytes. 

OPEN "D" * 5 » "TEXT/BAS" » G4 

opens the file TEXT/BAS for direct access. Buffer 5 is used. The 
record length is 64. If this length does not match the record length 
assigned to TEXT/BAS when the file was originally OPENed, an error 
occurs. 

OPEN "0"» 7 * "INU/CONT" 

opens the sequential file “INV/CONT” for output. If “INV/CONT” does 
not exist, it is created. Information is written to the file sequentially, 
starting at the first byte. If the file does exist, any new information is 
written over the existing information; the file’s previous contents are 
lost. 
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OPEN "E"» 1. "LIST/EMP" 

opens the file LIST/EMP and extends it by appending new data to the 
end of the file. If “LIST/EMP” does not exist, OPEN “E” works the 
same way as OPEN “O”. 

OPEN "I"* 8 > "MGT" 

opens the sequential file “MGT” for sequential input. This enables you 
to retrieve information from the file (using INPUT# or LINE INPUT#). 
If “MGT” does not exist, a “File not found” error occurs. 

See the chapter on “Disk Files” for programming information. 


OPTION BASE 


OPTION BASE n 


Statement 


Sets n as the minimum value for an array subscript. 

N may be 1 or 0. The default is 0. 

if you use this statement in a program, it must precede the DIM 
statement. 

If the statement 

OPTION BASE 1 

is executed, the lowest value an array subscript may have is one. 
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OUT 


OUT port, data byte 


Statement 


Sends a data byte to a machine output port. 

Port is an integer between 0 and 255. Data byte is also an integer 
between 0 to 255. 

A port is an input/output location in memory. For information on Model 
4’s assigned ports, see the Technical Reference Manual. 

Example 

OUT 32,100 
sends 100 to port 32. 

PEEK 


PEEK(memory location) 


Function 


Returns a byte from memory location. 

The memory location must be in the range - 32768 to 65535. 

The value returned is an integer between 0 and 255. (For the 
interpretation of a negative value of memory location , see the 
statement VARPTR). 

PEEK is the complementary function of the statement POKE. 

Example 

A = PEEK (&H5A00) 
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POKE 



POKE memory location, data byte 


Statement 


Writes data byte into memory location. 

Both memory location and data byte must be integers. Memory 
location must be in the range -32768 to 65535. 

POKE is the complementary statement of PEEK. The argument to 
PEEK is a memory location from which a byte is to be read. 

PEEK and POKE are useful for storing data efficiently, loading 
assembly-language subroutines, and passing arguments (or results) to 
and from assembly-language subroutines. 

For more information, see Model 4’s Technical Manual. 

Example 

10 POKE &H5A00 * &HFF 


POS 


POS (number) 


Function 


Returns the position of the cursor. 

Number is a dummy argument. 

POS returns a number from 1 to 80 indicating the current 
cursor-column position on the display. 

Example 

PRINT TAB < 40) POS<0) 
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prints 40. The PRINT TAB statement moves the cursor to position 40, 
therefore, POS(0) returns the value 40. (However, since a blank is 
inserted before the “4” to accommodate the sign, the “4” is actually 
at position 41). 

Sample Program 


150 CLS 

160 A* = INKEY* 

170 IF A* = "" THEN 160 

180 IF POS(X) > 70 THEN IF A* = CHR*<32) 
THEN A* = CHR*(13) 

190 PRINT A*! 

200 PRINT A*5 
210 GOTO 160 


This program lets you use your printer as a typewriter (except that 
you cannot correct mistakes). Your computer keyboard is the 
typewriter keyboard. The program will keep watch at the end of a line 
so that no word is divided between two lines. 


PRINT 


PRINT data,... 


Statement 


Prints numeric or string data on the display. 

BASIC prints the values of the data items you list in this statement. 

You may separate the data items by commas or semicolons. If you 
use commas, the cursor automatically advances to the next tab 
position before printing the next item. (BASIC divides each line into 
five tab positions, at columns 0, 16, 32, 48, and 64). If you use 
semicolons, it prints the items without any spaces between them. 

A semicolon or comma at the end of a line causes the next PRINT 
statement to begin printing where the last one left off. If no trailing 
punctuation is used with PRINT, the cursor drops down to the 
beginning of the next line. 

Single-precision numbers with six or fewer digits that can be 
accurately represented in ordinary (rather than exponential) format, 






are printed in ordinary format. For example, 1E-7 is printed as 
.0000001; IE-8 is printed as IE-08. 

Double-precision numbers with 16 or fewer digits that can be 
accurately represented in ordinary format, are printed using the 
ordinary format. For example, ID-15 is printed as .000000000000001; 
ID-16 is printed as ID-16. 

BASIC prints positive numbers with a leading blank. It prints all 
numbers with a trailing blank. 

To insert strings into this statement, surround them with quotation 
marks. 

Examples 

PRINT "DO"; "NOT"! "LEAVE" i "SPACES". 

"BETWEEN"5 "THESE". "WORDS" 

prints on the display: 

DONOTLEAVESPACESBETWEENTHESEWORDS 

Sample Program 

G0 INPUT "ENTER THIS YEAR"! Y 
70 INPUT "ENTER YOUR AGE"iA 
80 INPUT "ENTER A YEAR IN THE FUTURE"5F 
90 N = A + (F - Y) 

100 PRINT "IN THE YEAR"F"YOU WILL BE"N"YEARS 
OLD" 

RUN 

Since F and N are positive numbers, PRINT inserts a space before 
and after them, therefore your display should look similar to this 
(depending on your input): 

IN THE YEAR 2004 YOU WILL BE 48 YEARS OLD 

If we had separated each expression in line 100 by a comma, 

100 PRINT "IN THE YEAR" .F . "YOU WILL 
BE">N ."YEARS OLD" 

BASIC would move to the next tab position after printing each data 
item. 
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Statement 


PRINT USING format; data item,... 


Prints data items using a format specified by you. 

Format consists of one or more field specifier(s), or any alphanumeric 
character. 

Data item may be string and/or numeric value(s). 

This statement is especially useful for printing report headings, 
accounting reports, checks, or any other documents which require a 
specific format. 

With PRINT USING, you may use certain characters (field specifiers) 
to format the field. These field specifiers are described below. They 
are followed by sample program lines and their output to the screen. 

Specifiers for String Fields: 

! Print the first character in the string only. 

PRINT USING “PERSONNEL” 

P 

\ spaces \ Print 2 + n characters from the string. If you type the 

backslashes without any spaces, BASIC prints two 
characters; with one space, BASIC prints three 
characters, and so on. If the string is longer than the 
field, the extra characters are ignored. If the field is 
longer than the string, the string is left-justified and 
padded with spaces on the right. To enter a 
backslash, press (CLEABXT1 

PRINT USING “\bbb\”; “PERSONNEL” 

(three spaces between the backslashes) 

PERSO 

& Print the string without modifications. 

10 A$ = “TAKE”:B$ = “RACE” 

20 PRINT USING “!”;A$; 

30 PRINT USING “&”;B$ 

RUN 

TRACE 







Specifiers for Numeric Fields: 

# Print the same number of digit positions as number 

signs ( # ). If the number to be printed has fewer 
digits than positions specified, the number is 
right-justified (preceded by spaces). Numbers are 
rounded as necessary. You may insert a decimal 
point at any position. In that case, the digits 
preceding the decimal point are always printed (as 
zero, if necessary). 

If the number to be printed is larger than the 
specified numeric field, a percent sign (%) is printed 
in front of the number. If rounding the number 
exceeds the field, a percent sign is also printed in 
front of the rounded number. 

PRINT USING “##.##”;111.22 
%111.22 

If the number of digits specified exceeds 24, an 
“Illegal function call” occurs. 

PRINT USING “##.##”;.75 
0.75 

PRINT USING “###.##”;876.567 
876.57 

+ Print the sign of the number. The plus sign may be 

typed at the beginning or at the end of the format 
string. 

PRINT USING “ + ##.## 

-98.45,3.50,22.22,-.9 

-98.45 +3.50 +22.22 -0.90 

PRINT USING “##.##+ 

-98.45,3.50,22.22,-.9 

98.54- 3.50+ 22.22+ 0.90- 

(Note the use of spaces at the end of a format string 
to separate printed values). 

- Print a negative sign after negative numbers (and a 

space after positive numbers). 

PRINT USING “###.#-”; -768.660 
768.7- 

** Fill leading spaces with asterisks. The two asterisks 

also establish two more positions in the field. 

PRINT USING “**####”; 44.0 
****44 
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$$ Print a dollar sign immediately before the number. 

This specifies two more digit positions, one of which 
is the dollar sign. 

PRINT USING “$$##.##”; 112.7890 
$112.79 

**$ Fill leading spaces with asterisks and print a dollar 

sign immediately before the number. 

PRINT USING “**$##.##”; 8.333 
***$8.33 

, Print a comma before every third digit to the left of 

the decimal point. The comma establishes another 
digit position. 

PRINT USING “####,.##”; 1234.5 
1,234.50 

Print in exponential format. The four exponent signs 
are placed after the digit position characters. To type 
the ", press (CLEAR) CT). You may specify any 
decimal point position. 

PRINT USING “.####-888888 

.8889E + 06 

_ Print next character as a literal character. 

PRINT USING “_!##.##_!”;12.34 

112.34! 

Sample Program 


420 

CLS: i 

A$ = "**$##,######,## DOLLARS" 

430 

INPUT 

"WHAT 

IS YOUR 

FIRST NAME 

“ 5 

F $ 

440 

INPUT 

"WHAT 

IS YOUR 

MIDDLE NAME" 

5 M$ 

450 

INPUT 

"WHAT 

IS YOUR 

LAST NAME" 

! 

L$ 

460 

INPUT 

"ENTER 

AMOUNT 

PAYABLE"? 

P 


470 

CLS : 

PRINT 

"PAY TO 

THE ORDER 

OF 

" 5 

480 

PRINT 

USING 

" ! ! ! ! 

"5 f$; " ♦ " 

5 

M$ 5 "."5 

400 

PRINT 

L$ 





500 

PRINT 

: PRINT 

USING 

A$5 P 




In line 480, each ! picks up the first character of one of the following 
strings (F$, M$, and again). Notice the two spaces in “llbllb”. 

These two spaces insert the appropriate spaces after the initials of 
the name (see below). Also notice the use of the variables A$ for 
format and P for item list in line 500. Any serious use of the PRINT 
USING statement would probably require the use of variables at least 
for item list rather than constants. (We’ve used constants in our 
examples for the sake of better illustration). 

# 
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A 


When the program above is run, the output should look something 
like this: 

WHAT IS YOUR FIRST NAME? JOHN 
WHAT IS YOUR MIDDLE NAME? PAUL 
WHAT IS YOUR LAST NAME? JONES 
ENTER AMOUNT PAYABLE? 12345.G 
PAY TO THE ORDER OF J. P. JONES 

*####$12,435.60 DOLLARS 


PRINT @ 


Statement 

PRINT@ location, 

PRINT® (row, column), 


Specifies exactly where printing is to begin. 

The location specified must be a number between 0 and 1919. It can 
also be a a pair of numbers (r, c), where 23 = >r= >0 and 
79 = >c = >0. 

Whenever you instruct BASIC to PRINT @ the bottom line of the 
display, it generates an automatic line feed; everything on the display 
moves up one line. To suppress this automatic line feed, use a trailing 
semicolon at the end of the statement. 

NOTE: If the string you are printing extends past column 80, BASIC 
prints the entire string on the next line. 

Examples 

PRINT 6 (11 .39) . "*" 

prints an asterisk in the middle of the display. The space between 
PRINT and @ is optional. 

PRINT @ 0. "*" 

prints an asterisk at the top left corner of the display. 
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SJ 

PRINT TAB 


PRINT TAB(n) 


Statement 



Moves the cursor to the n position on the current line. 

TAB may be used more than once in a print list. 

Since numeric expressions may be used to specify a TAB position, 
TAB can be very useful in creating tables, graphs of mathematical 
functions, etc. 

TAB can’t be used to move the cursor to the left. If the cursor is to 
the right of the specified position, the TAB statement is simply 
ignored. 

The first parenthesis must be typed immediately after the word TAB. 

If n is greater than 80, BASIC divides n by 80 and uses the remainder 
of the division as the tab position. For example, if you enter the line: 

PRINT "NAME"! TABI85)! "AMOUNT" 


BASIC converts TAB(84) into TAB(4). Since the cursor is already at 
column five after printing NAME, BASIC moves the string AMOUNT to 
the next line. If, instead, you had typed TAB(85), BASIC would print 
AMOUNT on the same line. 

If the string you are printing is too long to fit on the current line, 

BASIC moves the string to the next line. 

Example 

PRINT TAB(5) "TABBED 5"! TAB(25) "TABBED 25" 


Notice that no punctuation is needed after the TAB modifiers. 

Sample Program 


220 

CLS 



230 

PRINT 

TAB 

(2) 


"DESCRIPT 

ION 

240 

PRINT 

TAB 

(39 


PER ITEM" 

i 

245 

PRINT 

TAB 

(69 


"CATALOG N0."5 TAB( 
OF ITEM"! 

"QUANTITY"! TAB(51 
"TOTAL PRICE" 


1G) 

) "PRICE 
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Statement 


PRINT# butter, iteml, item2,... 


Prints data items in a sequential disk file. 

Buffer is the buffer number used to OPEN the file for input. 

When you first OPEN a file for sequential output, BASIC sets a 
pointer to the beginning of the file — that’s where PRINT# starts 
printing the values of the items. At the end of each PRINT# 
operation, the pointer advances, so values are written in sequence. 

A PRINT# statement creates a disk image similar to what a PRINT to 
the display creates on the screen. For this reason, make sure to 
delimit the data so that it will be input correctly from the disk. 

PRINT# does not compress the data before writing it to disk. It writes 
an ASCII-coded image of the data. 

Examples 

If A = 123*45 
PRINT* 1*A 

writes this nine-byte character sequence onto disk: 

H123.45B carriage return 

The punctuation in the PRINT list is very important. Unquoted 
commas and semicolons have the same effect as they do in regular 
PRINT statements to the display. For example, if A = 2300 and B = 

1.303, then 

PRINT# 1 * A ,B 

(ENTER) 

writes the data on disk as 

ti 2300 BBBBBBBBBB 1.303B carriage return 

The comma between A and B in the PRINT# list causes 10 extra 
spaces in the disk file. Generally you wouldn’t want to use up disk 
space this way, so you should use semicolons instead of commas. 

Files can be written in a carefully controlled format using PRINT# 
USING. You can also use this option to control how many characters 
of a value arc written to disk. 









For example, suppose A$ = “LUDWIG”, B$ = “VON”, and C$ = 
“BEETHOVEN”. Then the statement 

PRINT# 1. USING" !.!.\bSkl\" ;a$ ;b$ ;c$ 

would write the data in nickname form: 

L.V.BEET 

(In this case, we didn’t want to add any explicit delimiters.) See 
PRINT USING for more information on the USING option. 


PUT 


PUT buffer [,record] 


Statement 


Puts a record in a direct-access disk file. 

Buffer is the same buffer used to OPEN the file. 


Record is the record number you want to PUT into the file. It is an 
integer between 1 and 65535. If omitted, the current record number is 
used. 


This statement moves data from the buffer of a file into a specified 
place in the file. 

If record is higher than the end-of-file record number, then record 
becomes the new end-of-file record number. 

The first time you use PUT after OPENing a file, you must specify the 
record. The first time you access a file via a particular buffer, the next 
record is set equal to one. (The next record is the record whose 
number is one greater than the last record accessed). 

See the chapter on “Disk Files” for programming information. 

PUT 1 

writes the next record from buffer 1 to a direct-access file. 


PUT 1 . 25 

writes record 25 from buffer 1 to a direct-access file. 
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RANDOM 


r\ 


Function 


RANDOM 


Reseeds the random number generator. 

If your program uses the RND function, every time you load it, BASIC 
generates the same sequence of pseudorandom numbers. Therefore, 
you may want to put RANDOM at the beginning of the program. This 
will help ensure that you get a different sequence of pseudorandom 
numbers each time you run the program. 

RANDOM needs to execute just once. 

Sample Program 

600 CLS : RANDOM 

610 INPUT "PICK A NUMBER BETWEEN 1 AND 5"5 A 
620 B = RND(5) 

630 IF A = B THEN 650 

640 PRINT "YOU LOSE » THE ANSWER IS" B "--TRY 
AGAIN." 

645 GOTO 610 

650 PRINT "YOU PICKED THE RIGHT NUMBER -- YOU 


WIN!": GOTO 610 
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Statement 


READ variable,.... 


Reads values from a DATA statement and assigns them to variables. 

BASIC assigns values from the DATA statement on a one-to-one 
basis. The first time READ is executed, the first value in the first 
DATA statement is used; the second time, the second value is used, 
and so on. 

A single READ may access one or more DATA statements (each 
DATA statement is accessed in order), or several READs may access 
the same DATA statement. 

The values read must agree with the variable types specified in list of 
variables, otherwise, a “Syntax error” occurs. If the number of 
variables in the READ statement exceeds the number of elements in 
the DATA statement(s), an “Out of data” error message is printed. 

If the number of variables specified is lower than the number of 
elements in the DATA statement(s), subsequent READ statements 
begin reading data at the first unread element. 

Example 

READ T 

reads a numeric value from a DATA statement and assigns it to 
variable “T”. 

Sample Program 

This program illustrates a common application for the READ and 
DATA statements. 

40 PRINT "NAME'S "AGE" 

50 READ N$ 

60 IF N$="END" THEN PRINT "END OF LIST": END 
70 READ AGE 

80 IF AGE<18 THEN PRINT N$ » AGE 
80 GOTO 50 

100 DATA "SMITH * JOHN'S 30* "ANDERS* T * M♦"* 20 
110 DATA "JONES* BILL'S 15* "DOE* SALLY'S 21 
120 DATA "COLLINS* W.P.'S 17* "END" 





» 

REM 


REM 


Statement 


Inserts a remark line in a program. 

REM instructs the computer to ignore the rest of the program line. 
This allows you to insert remarks into your program for 
documentation. Then, when you look at a listing of your program, or 
someone else does, it will be easier to figure it out. 

If REM is used in a multi-statement program line, it must be the last 
statement in the line. 

You may use an apostrophe (’) as an abbreviation for REM. 

Sample Program 


OR 


110 DIM 0(20) 

120 REM CALCULATE AVERAGE VELOCITY 
130 FOR 1=1 TO 20 
140 SUM=SUM + V(I) 


110 DIM V(20) 

120 FOR 1=1 TO 20 'CALCULATE AVERAGE VELOCITY 

130 SUM=SUM + V(I) 

140 NEXT I 
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Statement 


RENUM [new line ] [, line ] [, increment] 


Renumbers a program, starting at line, using new line as the first new 
line and increment for the new sequence. 

If you omit new line, BASIC starts numbering at line 10. If you omit 
the line, it renumbers the entire program. If you omit increment, it 
jumps 10 numbers between lines. 

RENUM also changes all line number references appearing after 
GOTO, GOSUB, THEN, ON ... GOTO, ON .. . GOSUB, ON ERROR 
GOTO, RESUME, and ERL[relational operator]. 

Examples 

RENUM 

renumbers the entire resident program, incrementing by 10’s. The 
new number of the first line will be 10. 

RENUM 600 t 5000* 100 

renumbers all lines numbered from 5000 up. The first renumbered line 
will become 600, and an increment of 100 will be used between 
subsequent lines. 

RENUM 10000 * 1000 

renumbers line 1000 and all higher-numbered lines. The first 
renumbered line will become line 10000. An increment of 10 will be 
used between subsequent line numbers. 

RENUM 100t t 100 

renumbers the entire program, starting with a new line number of 100, 
and incrementing by 100’s. Notice that the commas must be retained 
even though the middle argument is gone. 

Error Conditions 

1. RENUM cannot be used to change the order of program lines. For 
example, if the original program has lines numbered 10, 20 and 
30, then the command: 


RENUM 15 > 30 






is illegal, since the result would be to move the third line of the 
program ahead of the second. In this case, an FC (illegal function 
call) error occurs, and the original program is left unchanged. 

2. RENUM will not create new line numbers greater than 65529. 
Instead, an FC error occurs, and the original program is left 
unchanged. 

3. If an undefined line number is used inside your original program, 
RENUM prints a warning message, Undefined line XXXX in 
YYYY”, where XXXX is the original line number reference and 
YYYY is the original number of the line containing XXXX. Note that 
RENUM renumbers the program in spite of this warning message. 
It does not change the incorrect line number reference, but it does 
renumber YYYY, according to the parameters in your RENUM 
command. 


RESTORE 


RESTORE [line] 


Statement 




Restores a program’s access to previously-read DATA statements. 

This lets your program re-use the same DATA lines. 

If line is specified, the next READ statement accesses the first item in 
the specified DATA statement. 

Sample Program 

160 READ X$ 

170 RESTORE 
180 READ Y* 

190 PRINT X*, Y* 

200 DATA THIS IS THE FIRST ITEM» AND THIS IS 
THE SECOND 

When this program is run, 

THIS IS THE FIRST ITEM THIS IS THE FIRST ITEM 

is printed on the display. Because of the RESTORE statement in line 
170, the second READ statement starts over with the first DATA item. 
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RESUME 



Statement 

RESUME [line] 

RESUME NEXT 



Resumes program execution after an error-handling routine. 

RESUME without an argument and RESUME 0 both cause the 
computer to return to the statement in which the error occurred. 

RESUME line causes the computer to branch to the specified line 
number. 

RESUME NEXT causes the computer to branch to the statement 
following the point at which the error occurred. 

A RESUME that is not in an error-handling routine causes a 
“RESUME without error” message. 

Examples 

RESUME 

if an error has occurred, this line transfers program control to the 
statement in which it occurred. 

RESUME 10 

if an error has occurred, transfers control to line 10. 

Sample Program 

10 ON ERROR GOTO 900 


900 IF (ERR=230) AND(ERL=90) THEN PRINT "TRY 
AGAIN" : RESUME 80 
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RETURN 



RETURN 


Statement 


Returns control to the line immediately following the most recently 
executed GOSUB. 

If the program encounters a RETURN statement without execution of 
a matching GOSUB, an error occurs. 

Sample Program 

330 PRINT "THIS PROGRAM FINDS THE AREA OF A 
CIRCLE" 

340 INPUT "TYPE IN A VALUE FOR THE RADIUS"; R 
350 GOSUB 370 

360 PRINT "AREA IS" 5 A: END 
370 A=3.14*R*R 
380 RETURN 



RIGHTS 


RIGHT$(sfr/ng, number) 


Function 


Returns the rightmost number characters of string. 

RIGHTS returns the last number characters of string. If LEN (string) is 
less than or equal to number, the entire string is returned. 

Examples: 

PRINT RIGHT*("WATERMELON "> 5) 

prints MELON. 

PRINT RIGHT*("MILKY WAY"> 25) 
prints MILKY WAY. 
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Sample Program 


850 

8G0 

870 

880 

830 

300 

910 


RESTORE : ON ERROR GOTO 880 
READ COMPANY* 

PRINT RIGHT$(COMPANY$ » 2), : GOTO 880 
END 

DATA “BECHMAN LUMBER COMPANY, SEATTLE, WA“ 
DATA "ED NORTON SEWER SERVICE, BROOKLYN, NY" 
DATA "HAMMON MANUFACTURING COMPANY, 

HAMMOND, IN" 


This program prints the name of the state in which each company is 
located. 


RND 


RND(number) 


Function 


^Generates a pseudorandom number between 0 and number. 

Number must be greater than or equal to 0 and less than 32768. 

RND produces a pseudorandom number using the current “seed” 
number. BASIC generates the seed internally, therefore, it is not 
accessible to the user. RND may be used to produce random 
numbers between 0 and 1, or random integers greater than 0, 
depending on the argument. 

RND(0) returns a single-precision value between 0 and 1, 
RND(number) returns an integer between 1 and number. For 
example, RND(55) returns a pseudorandom integer between 1 and 
55. RND(55.5) returns a pseudorandom number between 1 and 56 
(the argument is rounded). 

Examples 

A = RND(2) 

assigns A a value of 1 or 2. 

A = RND(45) 

assigns A a random integer between 1 and 45. 

PRINT RND (0) 

prints a decimal fraction between 0 and 1. 
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ROW 


/'> 


ROW (number) 


Function 


Returns the row position of the cursor. 

Number is a dummy argument. 

ROW finds the row in which the cursor is currently located and 
returns that row number. The 24 rows are numbered 0-23. 

Examples 

X = ROW(Y ) 

assigns the cursor’s current row number to X. 

Sample Program 

When you type a key, the program below prints: the keyboard 
character, the cursor’s row number and column number, and the 
character’s ASCII code. 

100 CLS 
110 R = 0: C = 0 

120 PRINT@<21#32)» "ROW"# "COLUMN" 

130 X$ = INPUT $(1) 

140 PRINT @(R #C) # X$ i 
150 C=POS(0): R=R0W(0) 

160 PRINT 0 (22 #32) »R >C5 
183 PRINT 0 (23 #32) > STRING$<20#32)5 
185 PRINT 0(23 #32) # "ASCII CODE IS 
"HEX$(ASC(X$) ) ; 

170 PRINT 0 (R »C)#""5 
180 GOTO 130 
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RSET 


RUN 


RSET field name = data 

Statement 

Sets data in a direct-access buffer field name. 


This statement is similar to LSET. The difference is that with RSET, 
data is right-justified in the buffer. 

See LSET for details. 


RUN [line] 

RUN f//espec[,R] 

Statement 


Runs a program. 

RUN followed by a line or nothing at all simply executes the program 
in memory, starting at line or at the beginning of the program. 

RUN followed by a filespec loads a program from disk and then runs 
it. Any resident BASIC program is replaced by the new program. 

Option R leaves all previously OPEN files open. If omitted, BASIC 
closes all open files. 

RUN automatically CLEARS all variables. However, it does not re-set 
the value of an ERL variable. 
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Examples 

RUN 

starts execution at lowest line number. 

RUN 100 

starts execution at line 100. 

RUN "PROGRAM/A" 
loads and executes PROGRAM/A. 

RUN "EDITDATA"» R 

loads and executes EDITDATA, leaving OPEN files open. 


SAVE 


Statement 

SAVE filespec [,A] [,P] 


Saves a program in a disk file under filespec. 

If filespec already exists, its contents will be lost as the file is 
re-created. 

SAVE without the A option saves the program in a compressed 
format. This takes up less disk space. It also helps in performing 
SAVEs and LOADs faster. BASIC programs are stored in RAM using 
compressed format. 

Using the A option causes the program to be saved in ASCII format. 
This takes up more disk space. However, the ASCII format allows you 
to MERGE this program later on. Also, data programs which will be 
read by other programs must usually be in ASCII. 

For compressed-format programs, a useful convention is to use the 
extension BAS. For ASCII-format programs, use /TXT. 

The P option protects the file by saving it in an encoded binary 
format. When a protected file is later RUN (or LOADed), any attempt 
to list or edit it fails. The only operations that can be performed on a 
protected file are: RUN, LOAD, MERGE, and CHAIN. 
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Examples 

SAME "FILE1/BAS.J0HNQD0E:3" 

saves the resident BASIC program in compressed format. The file 
name is FILE1; the extension is /BAS; the password is JOHNQDOE. 
The file is placed on Drive 3. 

SAVE "MATHPAK/TXT"> A 

saves the resident program in ASCII form, using the name 
MATHPAK/TXT, on the first non-write-protected drive. 


SGN 


SGN (number) 


Function 


Determines number’s sign. 

If number is a negative number, SGN returns -1. If number is a 
positive number, SGN returns 1. If number is zero, SGN returns 0. 

Examples 

Y = SGN(A * B) 

determines what the sign of the expression A * B is, and passes the 
appropriate number (-1,0,1) to Y. 

Sample Program 


G 1 0 

INPUT 

“ENTER A NUMBER”5 

X 

G20 

□ N 

SGN(X) + 2 GOTO 630 » 

640 > 

G30 

PRI 

NT 

“NEGATIVE"s END 


G40 

PRI 

NT 

"ZERO”: END 


650 

PRI 

NT 

"POSITIVE": END 
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SIN 


SIN (number) 


Function 


Computes the sine of number. 

Number must be in radians. To obtain the sine of number when 
number is in degrees, use SIN(number * .01745329). The result is 
always single precision. 

Examples 

PRINT SIN(7.96) 
prints .994385. 

Sample Program 

660 INPUT "ANGLE IN DEGREES"; A 

670 PRINT "SINE IS”! SIN A * .01745329) 


SOUND 


SOUND tone, duration 


Statement 


Generates a sound with the tone and duration specified. 

Tone is a digit between 0 and 7. It specifies the sound’s frequency 
level. Zero specifies the lowest frequency level; seven specifies the 
highest. 

Duration is an integer between 0 and 31. It specifies for how long the 
sound is to be generated. Zero specifies the shortest duration; 31 the 
longest. 

This statement can be especially useful in educational applications. 
For example, you can have the computer respond with a sound if a 
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user has answered a program’s prompt incorrectly (or vice versa). 

Sample Program 


10 INPUT "IN HONOR OF WHOM WAS THE CONTINENT OF 
AMERICA NAMED”5 A* 

Z0 IF A* ="AMERIGO VESPUCCI" THEN SOUND 7 ,2 ELSE 
GOTO 40 

30 PRINT "THAT'S RIGHT!": END 
40 SOUND 1 ,2 : PRINT "THE CORRECT ANSWER IS 
AMERIGO VESPUCCI" 


SPACES 


SPACE $(number) 


Function 


Returns a string of number spaces. 

Number must be in the range 0 to 255. 

Example 

PRINT "DESCRIPTION" SPACE*(4) "TYPE" SPACE*(9) 
"QUANTITY" 

prints DESCRIPTION, four spaces, TYPE, nine spaces, QUANTITY. 

Sample Program 


920 

PRINT 

"Here" 


930 

PRINT 

SPACE*(13) 

“is" 

940 

PRINT 

SPACE*(26) 

“an” 

950 

PRINT 

SPACE*(33) 

“example 

9G0 

PRINT 

SPACE*(52) 

“of" 

970 

PRINT 

SPACE*(G5) 

"SPACES“ 
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SPC 


SQR 


r> 


SPC (number) 


Function 


Prints a line of number blanks. 

Number is in the range 0 to 255. SPC does not use string space. The 
left parenthesis must immediately follow SPC. 

SPC may only be used with PRINT, LPRINT, or PRINT#. 

Example 

PRINT "HELLO" SPC(15) "THERE" 
prints HELLO, 15 spaces, THERE 


SQR (number) 


Function 


Calculates the square root of number. 
The number must be greater than zero. 
The result is always single precision. 

Example 

PRINT S0R(155.7) 
prints 12.478. 
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M 


Sample Program 


S80 

INPUT 

"TOTAL 

RESISTANCE 

(OHMS) 

" 5 R 

B90 

INPUT 

"TOTAL 

REACTANCE 

(OHMS) " 

; x 

700 

Z = SQR((R * 

R) + (X * 

X) ) 


710 

PRINT 

"TOTAL 

IMPEDANCE 

(OHMS) 

IS" z 


This program computes the total impedance for series circuits. 


STOP 


STOP 


Statement 



Stops program execution. 

When a program encounters a STOP statement, it prints the message 
BREAK IN, followed by the line number that contains the STOP. 

STOP is primarily a debugging tool. During the break in execution, 
you can examine variables or change their values. 

The CONT command resumes execution at the point it was halted. 

But if the program itself is altered during the break, CONT cannot be 
used. 

Sample Program 

22G0 X = RND(10) 

2270 STOP 
2280 GOTO)2260 

A random number between 1 and 10 is assigned to X, then program 
execution halts at line 2270. You can now examine the value X with 
PRINT X. Type CONT to start the cycle again. 
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STR$ 


r> 

y 


STR $(number) 


Function 


Converts number into a string. 

If number is positive, STR$ places a blank before the string. 

While arithmetic operations may be performed on number, only string 
functions and operations may be performed on the string. 

Example 

S$ = STR$(X) 

converts the number X into a string and stores it in S$. 

Sample Program 

10 A = l.S : B# = A : C# = VAL(STR$(A)) 

20 PRINT "REGULAR CONVERSION" TAB(40) "SPECIAL 
CONVERSION" 

30 PRINT B# TAB(40) C* 


STRINGS 


STRING$(number,characfer) 


Function 


Returns a string of number characters. 

Number must be in the range 0 to 255. 

Character is a string or an ASCII code. If you use a string constant, it 
must be enclosed in quotes. All the characters in the string will have 
either the ASCII code specified, or the first letter of the string 
specified. 

STRINGS is useful for creating graphs or tables. 
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Examples: 

B$ = STRING$(25 > "X") 


puts a string of 25 “X”s into B$. 

PRINT STRING$(50 » 10) 

prints 50 blank lines on the display, since 10 is the ASCII code for a 
line feed. 


Sample Program 

1040 CLEAR 300 

1050 INPUT "TYPE IN THREE NUMBERS BETWEEN 33 
AND 159" 5 N1 * N2 » N3 

1060 CLS: FOR I = 1 TO 4: PRINT STRING$(20* 
Nl): NEXT I 

1070 FOR J = 1 TO 2: PRINT STRING$(40, N2): 
NEXT J 

1080 PRINT STRING$(80 » N3) 


This program prints three strings. Each string has the character 
corresponding to one of the ASCII codes provided. 


SWAP 


SWAP variablel, variable2 


Statement 


Exchanges the values of two variables. 

Variables of any type may be SWAPped (integer, single precision, 
double precision, string). However, both must be of the same type, 
otherwise, a “Type mismatch” error results. 

Either or both of the variables may be elements of arrays. If one or 
both of the variables are non-array variables which have not been 
assigned values, an “Illegal Function Call” error results. 

Example 

SWAP FI#, F2# 

swaps the contents of FI# and F2#. The contents of F2# are put 
into FI#, and the contents of FI# are put into F2#. 
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Sample Program 


10 

A$= "ONE 

" :B$ 

_ it 

20 

PRINT 

A$ 

0$ 

B$ 

30 

SWAP 

A$ * 

B$ 


40 

PRINT 

A$ 

0$ 

B$ 

RUN 





ONE 

FOR 

ALL 



ALL 

FOR 

ONE 




":C$="FOR " 


SYSTEM 


SYSTEM [command] 


Statement 


Returns you to TRSDOS level. 

Command tells the system to execute the specified TRSDOS 
command and immediately return to BASIC. Your program and 
variables are not affected. If command is a constant, it must be 
enclosed in quotes. You can specify only the TRSDOS library 
commands, not the utilities. 

If you omit command, SYSTEM returns to the TRSDOS Ready mode. 
Your resident BASIC program is not retained in memory. 

NOTE: You cannot call DEBUG from BASIC. 

Examples 

SYSTEM 

returns you to TRSDOS. Your resident BASIC program is lost. 

SYSTEM "DIR" 

runs the TRSDOS command, DIR (print directory), then returns to 
BASIC. Your resident BASIC program remains intact. 
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u 

TAB 


TAB (number) 


Function 



Spaces to position number on the display. 

Number must be in the range 1 to 255. 

If the current print position is already beyond space number, TAB 
goes to that position on the next line. Space one is the leftmost 
position; the width minus one is the rightmost position. 

TAB may only be used with the PRINT and LPRINT statements. 

Sample Program 

10 PRINT "NAME" TAB(25) " AMOUNT":PR I NT 
20 READ A$ t B$ 

30 PRINT A$ TAB(25) B$ 

40 DATA "G.T.JONES"»"$25.00" 

RUN 

The display shows: 

NAME AMOUNT 

G.T.JONES $25.00 


TAN 



e 

Function 

TAN(number) 





Computes the tangent of number. 

Number must be in radians. To obtain the tangent of number when it 
is in degrees, use TAN (number * .01745329). The result is always 
single precision. 
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Examples 

PRINT TAN(7» 9G) 
. prints - 9.39702. 


Sample Program 

720 INPUT "ANGLE IN DEGREES"5 ANGLE 
730 T = TAN(ANGLE * .01745329) 

740 PRINT "TAN IS" T 


TIMES 


TIMES 


Function 


Returns the time of the day. 

This function lets you use the time in a program. 

The operator sets the time initially when TRSDOS is started up. When 
you request the time, TIMES supplies it using this format: 

14:47:18 

which means 14 hours, 47 minutes and 18 seconds (24-hour clock). 
To change the time, use the TRSDOS command, TIME. For example, 
SYSTEM "TIME 10:15:00" 

Example 

AS = TIMES 

stores the current time in A$. 

Sample Program 

1130 SYSTEM "TIME 10:15:00" 

1140 IF LEFT $(TIMES» 5) = "10:15" THEN PRINT 
"Time is 10:15 A.M.--time to pick up the 
mail." : END 
1150 GOTO 1140 
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TROFF, TRON 


Statements 

TROFF 

TRON 



Turn the “trace function” on/off. 

The trace function lets you follow program flow. This is helpful for 
debugging and analyzing of the execution of a program. 

Each time the program advances to a new line, TRON displays that 
line number inside a pair of brackets. TROFF turns the tracer off. 

Sample Program 

2290 TRON 

2300 X = X * 3.14159 
2310 TROFF 

Lines 2290 and 2310 above might be helpful in assuring you that line 
2300 is actually being executed, since each time it is executed [2300] 
is printed on the display. 

After a program is debugged, the TRON and TROFF statements can 
be removed. 
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USR 



USR [digit](argument) 


Function 


Calls a user’s assembly-language subroutine identified with digit and 
passes argument to that subroutine. 

The digit you specify must correspond to the digit supplied with the 
DEFUSR statement for that routine. If digit is omitted, zero is 
assumed. 

This function lets you call as many as 10 machine-language 
subroutines, then continue execution of your BASIC program. 
Subroutines must have been previously defined with DEFUSR[digit] 
statements. 

When BASIC encounters a USR call, it transfers control to the 
address defined in the DEFUSR[digit] statement. (This address 
specifies the entry point to your machine-language subroutine.) 

“Machine language” is the low-level language used internally by your 
computer. It consists of Z-80 microprocessor instructions. 
Machine-language subroutines are useful for special applications 
(things you can’t do in BASIC) and for doing things very fast (like to 
“white-out” the display). 

Writing such routines requires familiarity with assembly-language 
programming and with the Z-80 instruction set. For more information 
on this subject, see the Radio Shack book: TRS-80 
Assembly-Language Programming, by William Barden, Jr. 

Example 

X = USR5(Y) 

calls the machine-language routine USR5, previously defined in a 
DEFUSR5 = address statement. 

Passing arguments from BASIC to the subroutine: 

Upon entry to a USR subroutine, the following register contents are 
set up (for notation, the TRSDOS reference section in this manual): 

A = Type of argument in USR[digit] reference 

A = 8 if argument is double-precision 
A = 4 if argument is single-precision 
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HL 

A = 2 if argument is integer 

A = 3 if argument is string 

When the argument is a number, this register 
points to the argument storage area(ASA) 
described later. 

DE 

When the argument is a string, this register points 
to a string description, as follows: The first byte 
gives the length of the string. The next two bytes 
give the address where the string is stored: least 
significant byte (LSB) followed by most significant 


byte(MSB). 

Description of Argument Storage Area (ASA) — for numeric values 
only. 

For double-precision numbers: 

ASA + 3 Exponent in 128-excess form, e.g., a value of 128 


ASA + 2 

indicates a 0 exponent; a value of 66 indicates a 
-62 exponent. A value of 0 always indicates the 
number is zero. 

Highest seven bits of the mantissa with hidden 
(implied) leading one. Bit 7 is the sign of the 
number(0 positive, 1 negative), e.g., a value of 
X’84’ indicates the number is negative and the 

MSB of the mantissa is X’84’. A value of X’04’ 
indicates the number is positive and the MSB of 
the mantissa is X’84’. 

ASA + 1 

ASA 

ASA - 1 

ASA - 2 

ASA - 3 

Next MSB of the mantissa. 

Next MSB. 

Next MSB. 

Next MSB. 

Next MSB. 


ASA - 4 Lowest eight bits of the mantissa. 

For single-precision numbers: 

ASA LSB of the mantissa. 


ASA + 1 
through 

ASA + 3 

Same as for double-precision numbers. 

For integers: 

ASA 

ASA + 1 

LSB of the number 

MSB of the number. Together, the two bytes 
represent the number in signed, two’s complement 
form. 





Your routine can call BASIC’s FRCINT routine to put the argument 
into HL in 16-bit, signed two’s complement form. The address of 
FRCINT is stored in [X’2603\ X’2604]. 

For example, you can put the following code at the beginning of your 
subroutine: 


FRCINT EQU 

2G03H 

5CONCERTS USR ARGUMENT 
5TO INTEGER IN HL 

LD 

HL »CTNU 

5(HL)=CONTINUATION 

5 ADDRESS 

PUSH 

HL 

5SAVE IT FDR RETURN 

5FROM FRCINT 

LD 

HL *(FRCINT) 

5(HL)=F0RCE INTEGER 
5R0UTINE 

JP 

(HL) 

5D0 FRCINT ROUTINE 


Returning values from the subroutine to BASIC: 

If the USR[digit] argument is a variable, you can modify its value by 
changing the ASA or string contents, as pointed to by HL or DE. For 
example, the statement: 

X=USR1(AX) 

transfers control to the USR1 subroutine, with HL pointing to the 
two-byte ASA for integer variable A%. Suppose you modify the 
contents of its storage area. When you do a RET instruction to return 
to BASIC, A% will have a new value, and X will be assigned this new 
value. 

In general, USR[digit](argument) will return the same type of value as 
argument. However, you can use BASIC’s MAKINT routine to return 
an integer value. The address of the MAKINT routine is stored at 
[X’2605’,X’2606’]. 

For example, you might include the following code at the end of your 
program to return a value to BASIC: 


MAKINT 


EQU 

LD 

2G05H 

HL *VAL 

5VAL IS THE VALUE 

TO 

PUSH 

HL 

;be returned. 

5SAVE VALUE IN STACK 

LD 

HL* (MAKINT) 

5RESTORE VAL INTO 

HL 

EX 

(SP)* HL 

!AND PUT MAKINT 


RET 


UNTO STACK 
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Function 


U 

VAL 


VAL(string) 



Calculates the numerical value of string. 

VAL is the inverse of the STR$ function; it returns the number 
represented by the characters in a string argument. This number may 
be integer, single precision, or double precision, depending on the 
range of values and the rules used for typing all constants. 

For example, if A$ = “12” and B$ = “34” then VAL(A$ + + B$) 

returns the value 12.34 and VAL(A$ + “E” + B$) returns the value 
12E34, that is, 12 * 10~34. 

VAL terminates its evaluation on the first character which has no 
meaning in a numeric value. 

If the string is non-numeric or null, VAL returns a zero. 

Examples 

PRINT UAL("100 DOLLARS") 
prints 100. 

PRINT VAL("1234E5") 
prints 1.234E + 08. 

B = VAL("3" + + "2") 

assigns the value 3 to B (the asterisk has no meaning in a numeric 
term). 

Sample Program 

10 READ NAMES*# CITY*# STATE*# ZIP* 

20 IF VAL(ZIP*) < 90000 OR VAL(ZIP*) > 96699 
THEN PRINT NAME* TAB(25) "OUT OF STATE" 

30 IF VAL(ZIP*) > 90801 AND VAL(ZIP*) <= 90815 
THEN PRINT NAME* TAB(25) "LONG BEACH" 
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VARPTR 


VARPTR (variable) 
or 

VARPTR (# buffer) 


Function 


Returns the absolute memory address. 

VARPTR can help you locate a value in memory. When used with 
variable, it returns the address of the first byte of data identified with 
variable. 

When used with buffer, it returns the address of the file’s data buffer. 

If the variable you specify has not been assigned a value, an “Illegal 
Function Call” occurs. If you specify a buffer that was not allocated 
when loading BASIC, a “Bad file number” error occurs. (See Chapter 
1 for information on how to load BASIC.) 

VARPTR is used primarily to pass a value to a machine-language 
subroutine via USR[digit]. Since VARPTR returns an address which 
indicates where the value of a variable is stored, this address can be 
passed to a machine-language subroutine as the argument of USR; 
the subroutine can then extract the contents of the variable with the 
help of the address that was supplied to it. 

If VARPTR returns a negative address, add it to 65536 to obtain the 
actual address. 

If VARPTR(integer variable) returns address K: 

Address K contains the least significant byte (LSB) of the 2-byte 
integer. 

Address K + 1 contains the most significant byte(MSB) of the integer. 

If VARPTR(single-precision variable) returns address K: 

(K)* = LSB of value 

(K + 1) = Next most significant byte(Next MSB) 

(K + 2) = MSB with hidden (implied) leading one. Most 

significant bit is the sign of the number 
(K + 3) = exponent of value excess 128(128 is added to the 

exponent). 


r\ 


r\ 
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If VARPTR(double-precision variable) returns K: 


(K) 

(K + 1) 

(K + . . .) 
(K + 6) 

(K + 7) 


= LSB of value 
= Next MSB 
= Next MSB 

= MSB with hidden(implied) leading one. Most significant 
bit is the sign of the number. 

= exponent of value excess 128(128 is added to the 
exponent). 


For single and double-precision values, the number is stored in 
normalized exponential form, so that a decimal is assumed before the 
MSB. 128 is added to the exponent. Furthermore, the high bit of MSB 
is used as a sign bit. It is set to 0 if the number is positive or to 1 if 
the number is negative. See examples below. 

*(K) signifies “contents of address K” 

If VARPTR(string variable) returns K: 


(K) = length of string 

(K + 1) = LSB of string value starting address 

(K + 2) = MSB of string value starting address 


The address will probably be in high RAM where string storage space 
has been set aside. But, if your string variable is a constant(a string 
literal), then it will point to the area of memory where the program line 
with the constant is stored, in the program buffer area. Thus, program 
statements like A$ = “HELLO” do not use string storage space. 


For all of the above variables, addresses (K-1) and (K-2) stores the 
TRS-80 Character Code for the variable name. Address(K-3) contains 
a descriptor code that tells the computer what the variable type is. 
Integer is 02; single precision is 04; double precision is 08; and string 
is 03. 


VARPTR(array variable) returns the address for the first byte of that 
element in the array. The element consists of 2 bytes if it is an integer 
array; 3 bytes if it is a string array; 4 bytes if it is a single precision 
array; and 8 bytes if it is a double precision array. 

The first element in the array is preceded by: 

1. A sequence of two bytes per dimension, each two-byte pair 
indicating the “depth” of each respective dimension. 

2. A single byte indicating the total number of dimensions in the 
array. 

3. A two-byte pair indicating the total number of elements in the 
array. 

4. A two-byte pair containing the ASCII-coded array name. 
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r> 


5. A one-byte type-descriptor(02 = Integer, 03 = String, 04 = 

Single = Precision, 08 = Double-Precision). 

Item 1 immediately precedes the first element, Item 2 precedes Item 
1, and so on. 

The elements of the array are stored sequentially with the first 
dimension-subscripts varying “fastest”, then the second, etc. 

Examples 

A! = 2 is stored as follows: 


2 = 10 Binary, normalized as .1E2 = .1 x 10 (to the second) 

So exponent of A is 128 + 2 = 130 (called excess 128) 

MSB of A is 10000000; however, the high bit is changed to zero since 
the value is positive(called hidden or implied leading one). 

So A! is stored as 


Exponent(K + 3) 

130 

A! = - .5 is stored as 

Exponent(K + 3) 
128 

A! = 7 is stored as 

Exponent(K +3) 

131 

A!= -7: 


MSB(K + 2 ) Next MSB(K + 1) LSB(K> 
0 0 0 


MSB(K + 2 ) Next MSB(K + 1) LSB(K > 
128 0 0 


MSB(K + 2) Next MSB(K + 1) LSB(K> 
9G 0 0 



Exponent(K + 3) MSB(K + 2) Next MSB(K + 1> LSB(K> 

131 224 0 0 

Zero is stored as a zero-exponent. The other bytes are insignificant. 
Y = USRl(VARPTR(number)) 

If number is an integer value, VARPTR(number) finds the address of 
the least significant byte of number. This address is passed to the 
subroutine, which in turn passes its result to Y. 


o 
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WAIT 


WAIT port, integerl \,integer2] 


Statement 



Suspends program execution until a machine input port develops a 
specified bit pattern. (A port is an input/output location.) 

The data read at the port is exclusive OR’ed with integer2, then 
AND’ed with integerl. If the result is zero, BASIC loops back and 
reads the data at the port again. If the result is nonzero, execution 
continues with the next statement. If integer2 is omitted, it is assumed 
to be zero. 

It is possible to enter an infinite loop with the WAIT statement. In this 
case, you will have to manually restart the machine. To avoid this, 
WAIT must have the specified value at port number during some point 
in program execution. 

For information on Model 4’s assigned ports, refer to the Technical 
Reference Manual. 

Example 

100 WAIT 3Z»Z 
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WHILE .... WEND 


WHILE expression 


Statement 


{loop statements} 
WEND 


Execute a series of statements in a loop as long as a given condition 
is true. 


If expression is not zero (true), BASIC executes loop statements until 
it encounters a WEND. BASIC returns to the WHILE statement and 
checks expression. If it is still true, BASIC repeats the process. If it is 
not true, execution resumes with the statement following the WEND 
statement. 


WHILE/WEND loops may be nested to any level. Each WEND 
matches the most recent WHILE. An unmatched WHILE statement 
causes a “WHILE without WEND” error, and an unmatched WEND 
causes a “WEND without WHILE” error. 

Sample Program 

30 'BUBBLE SORT ARRAY A$ 

100 FLIPS=1 'FORCE ONE PASS THRU LOOP 

110 WHILE FLIPS 

115 FLIPS=0 

120 FOR 1=1 TO J-l 

130 IF A$(I)>A$(1+1)THEN SWAP A$(I)» A$(I+1): 

FLIPS= 1 
140 NEXT I 
150 WEND 

This program sorts the elements in array A$. Control falls out of the 
WHILE loop when no more SWAPS are performed on line 130. 
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WRITE 



WRITE [data ,... ] 


Statement 



Writes data on the display. 

WRITE prints the values of the data items you type. If data is omitted, 
BASIC prints a blank line. The data may be numeric and/or string. 
They must be separated by commas. 

When the data are printed, each data item is separated from the last 
by a comma. Strings are delimited by quotation marks. After printing 
the last item on the list, BASIC inserts a carriage return. 

Example 

10 D=95:B=7G:U$="G00D BYE" 

20 WRITE D. B» V$ 

RUN 

95 > 7G > "GOOD BYE" 

Ready 
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WRITE# 


rs 


WRITE# buffer, data,... 


Statement 


Writes data to a sequential-access file. 

Buffer must be the number used to OPEN the file. 

The data you enter may be numeric or string expressions. 

WRITE# inserts commas between the data items as they are written 
to disk. It delimits strings with quotation marks. Therefore, it is not 
necessary to put explicit delimiters between the data. 

The items on data must be separated by commas. 

WRITE# inserts a carriage return after writing the last data item to 
disk. 

For example, if 

A$="MICROCOMPUTER" and B$="NEWS" 
the statement 

WRITE#1* A* »B$ 
writes the following image to disk: 

"MICROCOMPUTER" ♦"NEWS" 


r"N 
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Appendix A/ Job Control Language 


The TRSDOS Job Control Language (JCL) is one of the most 
powerful features of TRSDOS. It consists of: 

• TRSDOS commands 

• Macros 

• Special symbols 

You can use JCL to make your computer more “user friendly.” That 
is, you can write JCL programs that perform a variety of functions, 
such as FORMAT and BACKUP, and have TRSDOS execute these 
functions when the user types in one command line. 

If you have read the entries on the BUILD and DO commands, you 
know how to create a JCL file composed of TRSDOS commands. 

You can make this file more powerful by utilizing macros and other 
features of JCL. This section describes how. 

The steps for creating and using a JCL file are: 

1. Create a JCL file consisting of TRSDOS commands, macros, or 
special symbols. You can do this with the BUILD command, 
SCRIPSIT, or a BASIC program. 

2. Execute the JCL file with the DO command. This causes the JCL 
processor to: 

• Take control of the keyboard (for line input) 

• Read a line in the DO file exactly as if it came from the 
keyboard 

• Return control of the keyboard to the user when it reaches the 
last line. 

The following sections give complete information on all the JCL 
features: 

• Simple JCL Execution 

• Simple JCL Compiling 

• Advanced JCL Compiling 
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Simple ICL Execution 

This section lists the execution macros and gives examples on how to 
create and run a JCL file. 

Creating a JCL File 

A JCL file contains characters normally available from the keyboard 
(ASCII characters). 

There are several ways to create a JCL file: the BUILD library 
command lets you create or extend a JCL file, but it does not let you 
edit an existing file. You can create and edit a JCL file with a BASIC 
program. A word processing system, such as SCRIPSIT, will also let 
you create or edit a JCL file. 

Restrictions of JCL 

• A JCL file line cannot be longer than 79 characters. Depending on 
the JCL method used (execute only or compile), JCL either ignores 
all characters after the 79th or aborts the processing entirely. 

• Any program or utility with unpredictable prompts will not function 
properly when run from a JCL file. 

• Any program or utility which requires removing the system disk 
causes the JCL to abort. 

• You cannot execute certain TRSDOS library commands and utilities 
from a JCL file. The commands and utilities NOT valid from a JCL 
file are : certain BACKUP commands, BUILD, certain CONV 
commands, all (X) commands, DEBUG, certain PURGE 
commands, SYSGEN, and SYSTEM (SYSTEM = ) command. 

• As a general rule, you should not use a library command or utility 
when you specify the QUERY parameter. 
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Table 1/ Execution Macros 


Group Macro 

Macro Group Description Macros Description 


Execution 

Comment 


.Comment Displays a comment on 

the screen during 
execution. Comments 
are written to 

SYSTEM/JCL. 

Termination 

Macros 

Terminate 

execution. 

//ABORT Stops execution, 

displays “Job aborted". 
Returns to TRSDOS or 
BASIC Ready. 

//EXIT Stops execution, 

displays “Job done”. 
Returns to TRSDOS or 
BASIC Ready. 

//STOP Stops execution. 

Returns control to the 
user program. 

Pause/Delay 

Macros 

Provide 

special 

functions. 

//PAUSE Suspends execution and 

displays a message. 

//DELAY Suspends execution and 

displays a message for 
a specified amount of 
time. 

//WAIT Suspends execution 

depending upon the 
setting of the system 
clock. 

//SLEEP Suspends execution for 

a predetermined amount 
of time. 

Alert 

Macros 

Provide 
video and 
audio alerts. 

//FLASH Flashes a message on 

the screen a specified 
number of times. 

//ALERT Provides an audible 

signal to the operator. 

Keyboard 

Macros 

Accept key¬ 
board input. 

//KEYIN Selects predefined 

blocks of JCL lines. 

//INPUT Inputs a line of infor¬ 

mation from the 
keyboard. 
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JCL Execution Macros 

A macro is a pre-defined JCL instruction. //ABORT is an example of a 
macro symbol. Macro symbols must start at the first character position 
in the line. An execution macro cannot be the first line in a JCL 
file. 

The JCL execution macros are: 

//ABORT 

Use this macro to exit a JCL procedure (if an error is encountered) 
and return to the program that initiated the DO command. 

Your system returns you to the calling program if your JCL processing 
logic detects an error. The following message: 

Job aborted 

is displayed when an error is encountered. 

//ALERT [( ]tone,silence,tone,silence. . . .[)] 

Use this macro to produce tones to the operator. //ALERT can 
generate up to eight different tones using the sound generator inside 
the computer. 

You could use this macro to signify the end of a large JCL procedure. 
It could also be used during the execution of a procedure to bring 
attention to a specific process. 

Tone is controlled by a number ranging from 0 - 7, with 7 producing 
the lowest tone and 0 producing the highest tone. 

The tone is followed by a period of silence which you select with a 
second number ranging from 0 - 7, with 7 producing the longest 
period of silence and 0 producing the shortest period of silence. Tone 
and silence must be entered as number pairs (for example, “1,0”). 

You can enter as many number pairs as can fit on one line. 

You can repeat the tone-silence sequence by enclosing the entire 
string in parentheses. The sequence keeps repeating until you press 
(ENTER) , which continues execution of the JCL. Pressing (BREAK) aborts 
the JCL. 

Any value entered (for tone or silence) is used in its modulo 8 form. 
That is, if you enter the number 8, a zero value is assumed. For 
example, the value 10 produces the tone assigned to 2. 

//DELAY duration 

The //DELAY macro provides a definite timed pause with execution 
automatically continuing at the end of the delay. The actual delay will 
be approximately 0.1 second per count. The count ranges from 1 to 
256. Thus, a delay of from 0.1 second to 25.6 seconds is possible. 


A-6 











You could use the //DELAY macro to suspend execution long enough 
for you to make sure the printer is ready to print. 

The execution time of a //DELAY macro will vary slightly according to 
the speed TRSDOS is running under (FAST or SLOW). See the 
SYSTEM library command. 

//EXIT 

Use this macro to halt execution of JCL processing and return to the 
program that initiated the DO command. 

If you do not enter a termination macro in a JCL file, the JCL 
processing terminates when it reaches the end of the file (as if //EXIT 
were the last line in the JCL file). The following message is displayed: 

Job done 

This message indicates a normal conclusion of the JCL file. 

You should use //EXIT if the conclusion of the JCL file also represents 
the conclusion of the job that is running. So, //EXIT can be used to 
conclude a program that does not require any more keyboard input, 
and needs to return to TRSDOS Ready or BASIC Ready after it 
finishes. 

To conclude a program that requires additional keyboard input, use 
the //STOP macro. Using the //EXIT macro would terminate the 
program. 

//FLASH [duration] message 

This macro flashes message on and off the video screen, duration is 
the number of times the message will flash and can be any number 
from 0 to 255. If duration is not specified, the message flashes 256 
times. The message is any comment that you want displayed (up to 
72 characters). 

//KEYIN [comment string ] 

Use this macro to prompt for a single character entry (0 - 9), with the 
entire //KEYIN line being displayed. 

During execution, press the appropriate character (0 - 9) to select the 
corresponding execution block in a JCL file. There can be up to ten 
execution blocks in a JCL file, each tagged with // and a number 0 - 9. 

Do not use //KEYIN to enter data at execution time. If you do need to 
enter data at execution time, use the //INPUT macro. 

//INPUT [message string ] 

Use this macro to input a line from the keyboard during JCL 
execution. With this macro, control of the keyboard is temporarily 


A-7 






returned to the operator. Now, any command can be typed on the 
keyboard and then passes to the system. 

The number of characters allowed in the input line depends on where 
the JCL execution is when the //INPUT is encountered. For example, 
if the JCL is executing at the TRSDOS Ready level, then you can 
enter up to 80 characters, the same as for a normal TRSDOS 
command. If the //INPUT is encountered after going into BASIC, then 
you can enter up to 255 characters. 

When you use the //INPUT macro, you should exercise some caution 
to assure that the command typed in is valid at the level it will be 
executed. For example, if you enter a program name incorrectly, the 
error message “Program not found” is displayed and the JCL 
execution aborts. 

//PAUSE [message string] 

When this macro is encountered in an executing JCL file, it is 
displayed on the screen along with a message. You can use the 
message to inform the operator why the pause was ordered. Press 
(ENTER) to resume JCL execution, or press (BREAK) to abort the JCL. 

The //DELAY, //WAIT, and //SLEEP macros are similar to the 
//PAUSE macro, and are used to give JCL execution a specific delay 
period. 

//SLEEP hh:mm:ss 

Use this macro to put the system “to sleep” for the amount of time 
you specify. 

//SLEEP adds the specified time to the current system time and waits 
until that time to begin or resume execution. 

Suppose you have two programs that begin execution every morning 
at 10 o'clock and each program runs for two hours. You could 
execute the first program and have the //SLEEP macro “halt” 
execution of the second program for an hour lunch break. After the 
system "sleeps” for the specified hour, the second program is 
executed. 

//STOP 

Use this macro to halt execution of a JCL file and return keyboard 
control to the applications program that requests additional keyboard 
input. 

If you do not use the //STOP macro, you automatically return to 
TRSDOS Ready or BASIC Ready. You can also use the //ABORT 
and //EXIT macros to force an end to the JCL execution and return to 
TRSDOS Ready or BASIC Ready. ^ 
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//WAIT hh:mm:ss 




The //WAIT macro is similar to //DELAY, except that the length of the 
delay depends on the setting of the system clock. 

The //WAIT macro puts the entire system in a “sleep” state until the 
system clock matches the time you specified. 

You can set the system clock with the TIME library command. You 
can also set the time from a JCL file by using a direct execution of 
the TIME library command, or with the //INPUT macro. Set the clock 
in the format hh:mm:ss. 


Examples 

The easiest JCL file to understand is one containing only commands. 

Use the BUILD command to create the following JCL file named 
START/JCL: 

DEVICE 

FREE 

If you issue a DO = START command (see the DO library 
command), your computer displays the device table, lists free space 
information about all enabled drives, and returns to TRSDOS Ready. 

Because an execution macro cannot be the first line in a JCL file, 
you could use an execution comment to display an informative 
message as the JCL file begins to execute. An execution 
comment begins with a period, which must be in the first 
character position of the line. You could label START/JCL as 
follows: 


. This program executes the DEVICE and FREE 
commands• 

DEVICE 

FREE 

//EXIT 

This comment describing the file’s purpose is displayed when the JCL 
executes. It shows the file’s purpose. Notice that we added the 
termination macro //EXIT. 

You can use the //PAUSE macro in START/JCL as follows: 


. This program executes the DEVICE and FREE 
library commands, 

//PAUSE Be sure the correct disk is in Drive 

DEVICE 

FREE 

//EXIT 


0! 
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This example suspends the JCL before DEVICE executes, so you can 
be sure that the correct disk is in Drive 0. Press (ENTER) to continue 
the JCL. 

You can use the //DELAY macro if you want to display an informative 
message to the operator. For example: 

. BE SURE THAT THE PRINTER IS TURNED ON! 

//DELAY 50 
DEVICE (P) 

FREE (P) 

//EXIT 

This example displays the above informative message and delays 
execution for approximately 5 seconds. After the delay, it executes 
DEVICE and FREE. 

If you want your system to execute START/JCL at a certain time of 
the day, use the //WAIT macro as follows: 

. This program runs at 2:15 a♦m ♦ 

//WAIT 02:15:00 

DEVICE 

FREE 

//EXIT 


This example displays the comment and then waits until the system 
clock matches the time of 02:15:00 specified in the //WAIT macro. It 
would then execute DEVICE and FREE, and return to TRSDOS 
Ready. 





. This program runs after a two-hour pause. 

//SLEEP 02:00:00 

DEVICE 

FREE 

//EXIT 

This example displays the comment and then "sleeps” for two hours. 

It then executes DEVICE and FREE, and returns to TRSDOS Ready. 

To use the //FLASH macro, modify START/JCL as follows: 

. This program executes the DEVICE and FREE 
commands. 

DEVICE 

//FLASH 10 Starting execution of FREE 

FREE 

//EXIT 

After DEVICE executes, the //FLASH line is displayed. It flashes on 
and off 10 times, as specified by the duration count. You can press 
(ENTER) to stop the flash and proceed to the next line. Pressing (BREAK) 
while the message is flashing aborts the JCL and displays the 
message “Job Aborted”. C 
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You can modify START/JCL to show several uses of //ALERT: 

. This program shows several uses of //ALERT. 

. TURN TO PAGE 4 AT THE TONE. 

//ALERT 0 »0 >1 >5 .0 ,2 
. PRESS ENTER TO BEGIN EXECUTION. 

//ALERT (1 .0 .7 .0) 

DEVICE 

FREE 

//EXIT 

The first tone tells you when to turn to page 4. The second tone 
repeats until you press (ENTER) to continue execution of the program 
or (BREAK) to abort the JCL. 

The next example shows how you could build a menu using execution 
comments to display different program choices. Using the //KEYIN 
macro lets you press a single key to execute the desired program. 

FREE :0 
FREE 
DEVICE 

pro 4 ram » 1 - 3 


There are two new macros used in this example. They are //number 
and III. 

IInumber is used to start a block of lines that corresponds to a value 
selected with the //KEYIN macro. This block extends until the next 
//number or to the III. 

Ill (the triple slash) is used to mark the end of all //number blocks. 
JCL stops looking for a match as soon as it encounters a III. 
Execution continues with the following line. 

In the above example, pressing 1, 2, or 3 selects the corresponding 
block of lines and runs the appropriate command. If you press a key 
other than 1, 2, or 3, all three //number blocks are ignored, and 
execution continues with the line after the III. 


. START/JCL 
. Program 1 is 
♦ Program 2 is 
. Prosfram 3 is 
//KEYIN Select 
//I 

FREE :0 

//EXIT 

112 

FREE 

//EXIT 

//3 

DEVICE 

//EXIT 

III 
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The lines following the III could contain other command options or an 
//ABORT macro to abort the JCL. One possible option could be to let 
the operator type in his own command. 

Consider the following rewrite of START/JCL that uses the //INPUT 
macro to let the operator type in his own command: 

. START/JCL 

. Program 1 is FREE :0 

. Program 2 is FREE 

. Program 3 is DEVICE 

//KEYIN Select program. 1 - 3 

//I 

FREE :0 

//EXIT 

112 

FREE 

//EXIT 

//3 

DEVICE 

//EXIT 

/// 

//INPUT Enter your own choice of command. 

//EXIT 

Now, if you press a key other than 1, 2, or 3 for the //KEYIN, the 
//INPUT line is displayed. 

You can also enter information directly into the system at the JCL 
level. For example, the //WAIT macro description mentions that you 
can set the time for the system clock in the middle of a JCL file. 

The following example prompts you to enter the TIME library 
command to set the system clock. After you input the time, the //WAIT 
macro pauses execution of the JCL file until the clock matches 
02:15:00 and then continues execution. 

♦ This program runs at 2:15 a ♦ m * 

//INPUT Enter the TIME command usinsf HH:MM:SS format* 

//WAIT 02:15:00 

DEUICE 

FREE 

//EXIT 


JCL Compiling 

The previous section explained how to create and use execute JCL 
files. This section describes some basic functions of the JCL compiler 
and shows practical examples of JCL files. 
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While an execute JCL file is useful, you need to use the compile 
phase of JCL for extra features. These extra features are explained in 
four parts: 

• Compilation Description and Terms 

• Conditional Decisions 

• Substitution Fields 

• Combining Files 

Compilation Description and Terms 

You can compile and/or execute any JCL file using the DO library 
command. If your JCL file contains only execution comments, 
commands, or execution macros, then you can completely skip the 
compile phase (using the “ = ” control character with the DO 
command). 

If, however, your JCL file contains “tokens” or labels, or must make 
logical decisions, then you must compile the file before executing it. 

The compile phase reads in the JCL file line by line, checking for 
directly executable lines, keyboard responses, and execution macros. 
The compile phase also evaluates any compilation statements and 
writes all resultant lines to a file called SYSTEM/JCL. After the 
compile phase completes, control is normally passed to the execution 
phase, which executes the SYSTEM/JCL file. 

As stated earlier, the JCL works by substituting lines in a file for 
keyboard entries. However, when you compile a JCL file, it can 
contain more than just a series of executable commands. (After the 
compile phase is completed, however, the SYSTEM/JCL file does 
contain only executable lines.) 

You can include the following statements in a JCL file you intend to 
compile: 

• Directly executable commands (DIR, BASIC, etc.) 

• Pre-arranged keyboard responses 

• JCL execution macros (listed in Table 1) 

• JCL conditional macros (listed in Table 2) 

• Labels 

• Another JCL file. When a JCL file “calls” another JCL file, 

TRSDOS transfers control to the called file and doesn’t return 
control to the calling file. 

We use several terms when discussing JCL compilation. They are: 

1. Token 

A token is a string of up to 8 alphanumeric characters. You can 
use both upper and lower case letters. Note: There is NO 
difference between upper and lower case letters for any JCL 
macro, token, or label. 
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You can use a token (1) as a true/false switch for logical decisions 
(see the //IF macro), and (2) as a character string value in 
substitution fields (see the SUBSTITUTION FIELDS section). 

2. Logical operator 

The simple logical operators are: 

AND (represented by the ampersand symbol “&”) 

OR (represented by the plus symbol “ + ”) 

NOT (represented by the minus symbol “ - ”) 

3. Label 

A JCL label is used to define the start of a JCL procedure, which 
allows many small JCL procedures to be combined into one large 
file. The format for a label is: 

@label 

The label can be up to 8 alphanumeric characters long. 
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Table 21 Conditional Macros 


Group Macro 

Macro Group Description Macros Description 


Compilation 

Comment 


//.Comment Acts like a visual log 

of the JCL file because 
they are displayed 
during compilation. 

These comments are not 
written to SYSTEM/JCL. 

Logical 

Macros 

Define con¬ 
ditional 
“blocks." 

//IF Defines the start of a 

conditional block. 

//END Defines the end of a 

conditional block. 

//ELSE Defines the alternative 

to a false //IF. 

Higher 

Order 

Logical 

Macros 

Provide for 
higher condi¬ 
tional logic 
statements. 

//SET Gives a token a logical 

true value. 

//RESET Gives a token a logical 

false value. 

//ASSIGN Sets a token’s value to 

true and assigns a 
character string value 
to the token. 

Termination 

Macro 


//QUIT Aborts JCL compiling if 

an invalid condition is 
detected. 

Merge 

Macro 


//INCLUDE Merges together two or 
more JCL files during 
compilation. 


0 
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Conditional Decisions 

Using //IF. //END. //ELSE 

The logical compilation macros (//IF, //END, and //ELSE) are used to 
establish logical “blocks” in a JCL file. When a JCL file is being 
compiled, these blocks are evaluated as either true or false. 

The //IF macro followed by a token determines if the block is true or 
false. 

To set a token true, specify it on the DO command line. To set a 
token false, do NOT specify it on the DO command line. 

These JCL macros produce the following results: 

1) If token is true ... 2) If token is false ... 

//IF token //IF token 

Include these lines. I snore these lines. 

//END //END 

3) If token is false, perform the alternative ... 

//IF token 

Isnore these lines. 

//ELSE 

Include these lines. 

//END 

With this type of logical decision capability, you can create a JCL file 
and then pick a course of action by typing in a “DO filespec ” 
command with different tokens. 

Examples 

Consider the following JCL file named START/JCL. 

. START/JCL for proJraw start-up 
SET *FF to FORMS/FLT 
FILTER *PR *FF 
//IF PR 1 

FORMS (CHARS=B0) 

//ELSE 

FORMS (CHARS=132) 

//END 

Assume that these are the first lines in a JCL file that begins 
execution of an applications program. 

To make the //IF PR1 test as true, issue the following DO command: 

DO START < PR 1 ) (ENTER) 

The 80 characters per line is selected. 
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If (PR1) is not specified on the DO command line, then the //IF test is 
false and the 132 characters per line is selected. 

Using //SET and //RESET 

JCL provides the //SET and //RESET macros to reduce the number of 
tokens in the DO command line. 

One basic use for //SET is to let one token set the value of another. 
For example: 

//if KI 

//SET PI 
//END 

This JCL file specifies that if Kl is true, then PI is set to a true 
condition also. 

Suppose that the token P2 is already SET and you want to give it a 
new value. Consider this example: 

//IF KI 
//RESET P2 
//END 

This JCL file specifies that if Kl is true, then P2 is reset to a false 
condition. 

Consider the JCL file named MENU/JCL: 

. MENU/JCL t revision 1 

SET *FF TO FORMS/FLT 

FILTER *PR *FF 

//IF PI 

//RESET P2 

FORMS < CHARS = 80) 

//ELSE 
//SET P2 

FORMS (CHARS=132) 

//END 

If you issue either one of the following commands: 

DO MENU (PI) (ENTER) 

DO MENU (PI t P2) (ENTER) 

the //IF macro tests PI as true; therefore P2 is reset to false, and the 
*FF and 80-character mode are applied. 

If you issue either one of the following commands: 

DO MENU (ENTER) 

DO MENU ( P2 ) (ENTER) 

the //IF macro tests false so the //ELSE macro sets P2 to true and the 
132-character mode is applied. 
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As previously mentioned, the //SET macro can be used to reduce the 
number of tokens that have to be entered on the DO command line. 
Consider the following SYSOPT/JCL example: 


* Establish TRSD05 system options 

//IF ALL 

//SET COMM 

//SET PR 

//SET SET 

//SET SRES 

//END 

//IF KI ALL 
//SET COMM 
//SET SET 
//END 
//IF COMM 

set * c 1 to com/dvr 
setcom (wo rd = 8) 

//END 
//IF PR 

set * f f to forms/fit 
filter *p r *f f 
forms (chars=80) 

//END 
//IF SET 
setKi (r a t e = 7) 

//END 
//IF SRES 
system ( s/s res = Z) 
system (sysres=3) 
system (sysres=10) 

//END 


This example shows how many different TRSDOS options can be 
established with a JCL file. The way it is structured, you can choose 
any or all of the options. 

If you did not use //SET, you would have to enter four separate 
tokens on the DO command line to establish all of the options, as 
follows: 

DO SYSOPT/JCL (COMM >PR »SET >SRES) (ENTER) 

If you specify “ALL” in the DO command line, COMM, PR, SET, and 
SRES are set to true conditions. 

If you specify “KIALL” in the DO command line, COMM and SET are 
set to true conditions. 

Notice the use of upper and lower case. As stated earlier, either 
upper or lower case letters can be used in any JCL macro, token, or 
label. This is also true when the line is a TRSDOS command, as are 
the lower case lines in this example. 
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You can improve the readability of a JCL file by using upper case for 
macros and lower case for executable lines, such as TRSDOS 
commands, or vice versa. 

Using //ASSIGN 

JCL provides the //ASSIGN macro to set a token’s logical value true, 
and to assign a character string value to a token. 

The syntax for the //ASSIGN macro is: 

//ASSIGN token =character string 

character string can consist of up to 32 characters. Any character on 
the keyboard is allowed except a double-quotation mark ( ” ). 

Error Conditions 

Any time you use //ASSIGN, there must be at least one character 
assigned as a value or the compiling aborts. 

Examples 

In any of the previous examples that used the //SET macro, the 
//ASSIGN macro could have been substituted. The character string 
value assigned to the token has no effect on the JCL logic. 

W In the following example, if the token A is true, the tokens PI, Kl, and 

PR are all set to true. This example assigns character string values to 
the tokens. 

. TEST/JCL 
//IF A 

//ASSIGN P1=PR0GRAM/BAS 
//ASSIGN K I =ALL 
//ASSIGN PR=80 
//END 

Using II. Comment and //QUIT 

Compilation comments (//. Comment) are not written to the 
SYSTEM/JCL file. They are displayed on the screen as they are 
encountered during compilation. Thus, they act as a visual status log 
of the compile. 

The //QUIT macro aborts the compilation stage if the JCL detects an 
invalid condition. This macro lets you make sure all needed tokens 
are entered before any execution takes place. 


3 
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Examples 

. START/JCL 
set *ff to forms/fit 
filter *p r *ff 
f o rms ( 1 iries=G0 ) 

//IF K I 

setKi (rate=5) 

//ELSE 

//. RATE was not set! 

//QUIT 

//END 

//EXIT 

If this JCL file is compiled without the token Kl being entered on the 
DO command line, the screen display shows: 

//. RATE was not set! 

'//QUIT 

No actual lines are executed from the SYSTEM/JCL file, because the 
compile phase was aborted before completion. The compilation 
comment tells the operator why the abort took place. 

If you substitute //ABORT for //QUIT in the previous example and then 
compile the JCL file without the token Kl, the following lines result: 

//. RATE was not set! 

. ST ART/JCL 
set *ff to forms/fit 
filter *p r *ff 
fo rms (1ines = G0) 

Job aborted 

The comment line is displayed as the file is being compiled. However, 
since //ABORT is an execution macro, the SYSTEM/JCL file finishes 
compiling and then executes until it reaches the //ABORT line! The 
//QUIT macro should be used in such a case rather than the 
//ABORT. 

Substitution Fields 

One of the most powerful features of the JCL is its ability to substitute 
and concatenate (add together) character strings to create executable 
lines. 

A substitution field is created by placing pound signs ( # ) around a 
token. When the file is compiled, this substitution token is replaced 
with its current value, either assigned on the DO command line or 
with the //ASSIGN macro. 




Examples 

. TEST/JCL 

set *ff to forms/flt 
filter *Pt *ff 
forms (c h ars = #C#) 
basic 
run"#P1#" 

//STOP 

This example uses two substitution fields: one in the FORMS 
command line representing the number of characters, and one in the 
RUN command line. 

If you issue the DO command: 

DO TEST (C=132»P1= PROGRAM 1) (ENTER) 

the lines written to the SYSTEM/JCL file are: 

. TEST/JCL 

set *ff to forms/flt 
filter *pr *ff 
fo rms (cha rs = 132) 
basic 

run " PROGRAM1" 

//STOP 

The compile phase substitutes the character string value of the tokens 
into the actual command line! 

The length of the replacement string does not have to be equal to the 
length of the token name between the # signs. 

To reduce the number of tokens needed on the DO command line, 
and to increase the program options at the same time, use the 
//ASSIGN macro as follows: 

. TEST/JCL 
//ASSIGN c =80 
//ASSIGN Pl = pro«framl 
//IF num2 
//ASSIGN c = 132 
//ASSIGN p1 = p ro3 ram2 
//END 

set *ff to forms/flt 
filter *pr *ff 
forms (chars=#C#) 
basic 
run"#Pl#" 

//STOP 






Specifying NUM2 overrides the 80-character printer filter and 
PROGRAM1 defaults. The values of C and PI are automatically set 
with the //ASSIGN tokens inside the //IF conditional block. 

Another use for substitution fields is replacing drive numbers. 

The following example shows how a FORMAT and BACKUP JCL file 
can be structured: 

. FB/JCL t FORMAT with BACKUP 
//PAUSE Insert disk to format in drive 
format : (n ame = "d at a 1" * q = n *ABS) 

backup :**S** 

//EXIT 

The token D represents the destination drive, and the token S 
represents the source drive. 

If you enter the command: 

DO FB/JCL (5 = 1 ,D = 2) (ENTER) 

the system pauses and prompts you to insert a disk in Drive 2. 

Press (ENTER) and the JCL file continues. It formats the disk in Drive 2, 
and then it executes the backup command with Drive 1 as the source 
drive and Drive 2 as the destination drive. 

The substitution fields can be used in message lines and comments 
as well as in executable command lines. 

Be careful when you want to display a single “#” in a comment or 
message. Consider the following example: 

//PAUSE Insert a disK in drive #1 

If the JCL file were executed only, this line would be properly 
displayed. However, if the JCL were compiled, an error would occur. 
For this line to be properly displayed in a compiled JCL, it would have 
to be written as: 

//PAUSE Insert a disk in drive ##1 

Another practical use for substitution fields is copying password 
protected files from one drive to another. 

♦ MODE/JCL file transfer 
copy pro3 raw 1♦«P#:0 :**D# 
copy pro3rarnZ.#P«:0 :#D# 
copy pro3ram3♦#P#:0 :#D« 
copy pro3ram4.#P#:0 :#D# 

//EXIT 

In this example, a group of files is copied from Drive 0 to a drive 
specified in the DO command. Also, you have to supply the proper 
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password for the copies to work. If you specify the wrong password, 
an error is displayed and the JCL aborts. 

Substitution fields can also be concatenated, or added together, to 
create new fields. For example: 

. ADD/JCL 
copy #F»/»E«:0 :1 
copy *F1»/»E#:0 si 
//EXIT 

This example uses two substitution fields, one for the filename and 
one for the extension. 

If you issue the DO command: 

DO ADD (F=SORT >E=CMD >F1 = S0RT1) (ENTER) 

the following SYSTEM/JCL file results after compiling: 

. ADD/JCL 

copy SORT/CMD:0 :1 
copy SORT 1/CMD:0 :1 
//EXIT 

As in previous examples, the //IF and //ASSIGN macros could be 
used to allow a single token to select the F, FI, and E tokens. 

Combining Files 

Most of the JCL examples in the previous sections have been very 
short. In a practical operating environment, this is often the case. 
However, each of these small files is taking up the minimum disk 
allocation of one gran and using one directory entry. 

To combine small files and save disk space, use the Label feature of 
JCL. You can also use the //INCLUDE macro to duplicate a JCL file 
inside of another JCL file, without having to retype the lines. 

Using //INCLUDE 

The //INCLUDE macro is used to merge together two or more JCL 
files during the compile phase. The syntax is: 

//INCLUDE filespec 

filespec is a JCL file. 

This command is similar to specifying the filespec in a DO command 
line. However, you cannot enter tokens or other information after the 
filespec. 

If you need to pass tokens to the included program, they will have to 
be established in the program that is doing the //INCLUDE. 








Error Conditions 

An //INCLUDE macro CANNOT be the last line in a JCL file. If it is, 
an “End of File Encountered” error occurs, and the JCL aborts. 

Examples 

This example shows two JCL files and the results of the compile 
phase. The two JCL files are: 

. TEST1/JCL . TEST2/JCL 

♦ comment line 1 . This comment is included 

//INCLUDE TEST2 

. comment line 2 

//EXIT 

If you issue the command 
DD TEST 1 (ENTER) 

the following SYSTEM/JCL file is produced: 

. TEST 1/JCL 
. comment line 1 
. TEST2/JCL 

. This comment is included 

. comment line 2 

//EXIT 

The compiling starts with the file named in the DO command line. As 
soon as the //INCLUDE is reached, all lines in the second JCL file are 
processed, and then the compiling returns to the rest of the original 
file. 

There is no limit to the number of non-nested //INCLUDE macros you 
can use, other than having enough disk space for the resulting 
SYSTEM/JCL file. 



Using JCL Labels 

The LABEL feature of JCL allows you to permanently merge together 
many small JCL procedures into one large file, and then access those 
procedures individually. This saves disk space and directory entry 
slots. 

Examples 

. TEST/JCL label example 
©FIRST 

. this is the first procedure 

//exit 

©SECOND 

. this is the next procedure 
©THIRD 

» this is the last procedure 
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This file contains three labels. To select any procedure, specify the 
label on the DO command line. 

The following rules determine how much of a labeled JCL file is 
included in the compile phase: 

1) If no label is specified on the DO command line, all lines from the 
beginning of the file up to the first label are compiled. 

2) If a label is specified, compiling includes all lines from the specified 
label until the next label or the end of the file is reached. 

DOing the TEST/JCL file using the @FIRST label would write the 
comment “. this is the first procedure” and the //EXIT macro to the 
SYSTEM/JCL file for execution. Specifying either of the other labels 
would include only the appropriate single comment line. 

If you compiled the file without specifying a label in the DO command, 
only the initial execution comment TEST/JCL label example” would 
be written in SYSTEM/JCL. 

There is no limit to the size of a labeled procedure. They can range 
from one to as many lines as you can fit on your disk. The only 
requirement is that a JCL file containing labels must be compiled. 

When you use labels in a JCL file, we recommend that you start the 
file with a comment line or some executable line other than a label. 

Suppose @FIRST is the first line in the following file: 

HFIRST 

♦ Print this comment 

If you issued a DO command for this file without specifying the 
@FIRST label, the compiling phase would receive the first line, see 
that it is a label, and quit. Since the compile is complete, the 
SYSTEM/JCL file would be executed! And since nothing was written 
to SYSTEM/JCL, its old contents are not erased. In other words, 
whatever lines had been compiled to the SYSTEM/JCL file from a 
previous DO command would now be executed. 


Advanced JCL Compiling 

The previous section on JCL compiling described the basic uses of 
tokens and compilation macros. If you do not understand the JCL 
Compiling section, please re-read it. If you actually type in and try the 
examples, you will get a better understanding of how to structure a 
JCL file for compiling. 

This section describes additional features and shows different ways to 
accomplish logical decision branching. These additional features are 
explained in four parts: 
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• Using the Logical Operators 

• Using Nested //IF Macros 

• Using Nested //INCLUDE Macros 

• Using the Special % Symbol 

Using the Logical Operators 

The logical operators used with the //IF macro (AND, OR, and NOT) 
specify the type of logical testing, and they are represented as 
follows: 

AND — ampersand ( & ) 

OR — plus sign ( + ) 

NOT — minus sign ( - ) 

All previous examples of //IF tested the logical truth or falseness of a 
token. You can accomplish more complex and efficient testing by 
using the logical operators. 

Consider the following series of examples using the tokens A and B: 

//IF -A 

. include these lines if A is not specified 

//END 

By using NOT ( - ), you can see if a token is false, which provides <fl| 
an alternative method to select a block of lines for compiling. 

//IF A+B 

. include these lines if A or B is specified 

//END 

//IF A&:B 

. include these lines if A and B are specified 

//END 

These examples show how multiple tokens may be tested in a single 
//IF statement. The first example is true if either A OR B is true. The 
second example is true only if both A AND B are true. 

You can use any combination of logical operators in an //IF statement. 

The following rules apply: 

• The expressions are evaluated from left to right. 

• Do not use parentheses because they abort the JCL compiling. 

• All logical operators have the same priority. 

You can combine the logical operators to test almost any 
arrangement of tokens. You can combine the logical operators to set 
up default conditions and to check for missing tokens, as the following 
examples demonstrate. 



A-26 





♦ CHECK/ 

JCL 

. CHECK 1/JCL 

//IF -S 


//IF -S+-D 

//ASSIGN 

tn 

ii 

•s 

//. You MUST 

//END 


//QUIT 

//IF -D 

//ASSIGN 

//END 

D = 2 

//END 


The CHECK example tests S and D individually, and assigns them 
default values if they were not true (that is, if they were not specified 
in the DO command line). 

The CHECK1 example is structured so that both S and D must be 
true (specified on the DO command line), or the JCL compiling aborts. 


Using Nested //IF Macros 

By definition, a conditional block begins with an //IF and concludes 
with an //END. 

When the //IF evaluates true, the lines between the //IF and the //END 
or an //ELSE (if one exists) are compiled. It is also possible to include 
other //IF - //END blocks within the main conditional block (called 
nesting). 

The //ELSE macro provides an alternative course of action in case an 
//IF evaluates false. It is also possible to have more //IF - //END 
statements following the //ELSE. Refer to the following examples: 


. TEST/JCL 
//IF A 
• comment 1 
//ELSE 
//IF B 
. comment 2 
//END (ends 

//END (ends 


the 

the 


//IF B statement) 
//IF A statement) 


If A evaluates true, comment 1 is written out, and the //ELSE is 
ignored. If A is false, B is tested. The comment 2 is written out only if 
B is true. Notice the two //END macros. There must be one //END for 
every //IF. 

You can document your own JCL files in the same way that we have 
documented these examples. 

Documenting //END macros increases the readability of the files, 
especially when you edit a file that you have created some weeks (or 
months) previously. 
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//IF A 






♦ Comment 

A 





//IF B 






♦ Comment 

B 





//IF C 






♦ Comment 

C 





//END 


( en 

d 5 

Third 

IF) 

//END 


< en 

d s 

Second 

IF) 

♦ Comment 

D 





//END 


( en 

d 5 

First 

IF) 


If the first //IF is false, all lines up to the corresponding //END are 
ignored. 

If the first //IF is true, Comment A and Comment D are written to 
SYSTEM/JCL. 

If //IF B is true, Comment B is also written to SYSTEM/JCL. If B is 
false, all lines up to the corresponding //END are ignored. 

The only time //IF C is considered is if both A and B test true. If C is 
true, Comments A through D are written to SYSTEM/JCL. 

Although not shown in the example, you can use the logical operators 
when nesting //IFs. 

Using Nested //INCLUDE Macros 

When you use the //INCLUDE macro, the included file can also 
contain another //INCLUDE macro. This is called nesting. The 
following rules apply: 

• The maximum nest level is five active //INCLUDE macros. 

• An //INCLUDE macro cannot be the last line in a JCL file. 

Example 

The following example uses three files to show how the lines in 
nested //INCLUDE files are processed: 

//. NEST0/JCL 

* nested procedure example (Nest 0) 

//INCLUDE nestl 

. this is the end of the primary JCL (Nest 0) 
//EXIT 

//. NEST1/JCL 

. this is the first nest (Nest 1) 

//INCLUDE nestZ 

. this is the end of the first nest (Nest 1) 

//. NEST2/JCL 

♦ this is the second nest (Nest 2) 
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If you save these JCL files as NEST0/JCL, NEST1/JCL, and 
NEST2/JCL and then compile and execute NEST0/JCL, the following 
SYSTEM/JCL results: 

//♦ NEST0/JCL 
//. NEST1/JCL 
//♦ NEST2/JCL 

. nested procedure example (Nest 0) 

« this is the first nest (Nest 1) 

• this is the second nest (Nest 2) 

. this is the end of the first nest (Nest 1) 

♦ this is the end of the primary JCL (Nest 0) 

The //INCLUDE macro can be used to compile a large JCL procedure 
from a series of smaller JCL routines. If the finished SYSTEM/JCL file 
is a procedure that will be executed many times, you can easily save 
it by copying SYSTEM/JCL to a file with another name. 

Using the Special % Symbol 

The % symbol is used to pass character values (in hex) to the system 
as though they came from the keyboard. The syntax is: 

%character value 

Below are some valid values and their results: 

Hex Value Result 


Position to next tab stop 
(every 8 columns) 
Linefeed 
Clear screen 


09 


0A 

IF 


The value of any printable character can also be used, although 
control characters (characters with a value less than hex 20) are 
generally used. (See Appendix C for a list of characters, values, and 
actions performed on the video display.) 

Examples 

You should place the clear screen character at the start of a line. For 
example: 

21F//PAUSE Insert disk in drive 1> press (ENTER) 

clears the screen and displays the JCL line in the top left corner of 
the screen. 

The tab and linefeed characters, used to position comments or lines 
on the screen, should always be placed AFTER the period in the 
comment line or the macro in an executable line. For example: 


w 
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♦ X09%09 This comment is positioned at the 
second tab stop* 

//PAUSE X0AX0AX0A This line appears 3 lines down 

If you place the character BEFORE the period, TRSDOS does not 
recognize it as a comment line and the JCL aborts. 

If you place the character AFTER the macro, the //PAUSE is 
displayed and the remaining message line is displayed 3 lines lower 
on the screen. 

Using the tab and linefeed characters in this manner can sometimes 
help to improve the readability of the messages displayed during JCL 
execution. 


Using TRSDOS ICL To Interface With Applications 
Programs 

This appendix describes how to use JCL to start up and control your 
applications programs. 

Two languages are discussed: BASIC and Z-80 assembly. 


Interfacing With BASIC 

A JCL file is the perfect method to interface between the operating 
system and the BASIC language. JCL can be used to create 
procedures that require only the inserting of a diskette to start up a 
program. Additionally, you can utilize the features of JCL from within a 
BASIC program. 

Examples 

To use a JCL file to initiate an automatic start-up of a BASIC 
program, you can use the AUTO library command to execute a JCL 
file. 

Assuming the JCL file is named BAS/JCL, issuing the command: 

AUTO DO BAS/JCL (ENTER) 

automatically executes the desired BASIC program every time the 
computer is booted with the AUTOed system disk. 

In order to execute a BASIC program from a JCL file, lay out the JCL 
file as follows: 

1. Establish any necessary drivers, filters, or other TRSDOS options. 

2. Enter BASIC with any necessary parameters (such as memory 
size and number of files). 

3. RUN the BASIC program. 
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4. Terminate the JCL execution with //STOP (which leaves control 
with BASIC). 

You can also enter a DO command directly from the TRSDOS Ready 
prompt to execute a BASIC program. 

To execute a JCL file once you have entered BASIC, the command 
format is: 

SYSTEM"DO filename " 

This command can be typed in directly or entered as a BASIC 
program line. 

Also, any JCL file called from BASIC should contain the //EXIT 
termination macro, so that control will return to TRSDOS Ready when 
the JCL file is completed. 

For example, suppose you want to use the JCL //ALERT macro to 
inform you when a lengthy BASIC procedure has completed. 

Following the lines containing the BASIC procedure, you could have a 
BASIC program line such as: 

1000 SYSTEM "DO = ALERT/JCL:0" 

which executes the ALERT/JCL file: 

. Your procedure is complete. Press (ENTER) to 
resume. 

//ALERT (1 ,0 .7 .0) 

BASIC 

//STOP 

When BASIC reaches line 1000, the JCL file ALERT/JCL is executed, 
sending a series of repeating tones out the tone generator. 

You are notified that your BASIC procedure has completed. Pressing 
(ENTER) ends the JCL alert and returns you to BASIC. 

There are two important points about this example. First, the 
comment line in the ALERT/JCL file is absolutely necessary, as a JCL 
file cannot start with an execution macro. Second, the “BASIC” 
statement will reload BASIC. If you want a particular program to be 
loaded and run, you can place its name on the command line or add 
the BASIC commands before the //STOP statement. The //STOP 
termination macro must be included to assure that keyboard control 
remains within BASIC. 

Although the example demonstrates an execute only JCL file, you can 
also call compiled JCL procedures from BASIC. You can even 
construct a SYSTEM “DO filespec [(parameters)]” command using 
BASIC string substitution. 

Any time you want to use a SYSTEM “DO filespec” command from 
BASIC to execute another BASIC program, you have to change the 
format of the command. To DO these types of JCL files from BASIC, 
use the commands: 
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SYSTEM (ENTER) 

DO filespec [(parameters)] (ENTER) 



Using this format for the command assures that a proper exit is made 
before the new JCL file is started. 

Controlling a BASIC program 

In some cases, the prompts in a BASIC program can be answered 
with a line from a JCL file. This is true if the program uses the INPUT 
or LINEINPUT BASIC statement to take the input. 

If the program uses the INKEY$ statement, response has to come 
from the keyboard rather than from a JCL file. If the program uses the 
proper input method, you can create a JCL for total hands-off 
operation as follows: 

1. Run through the BASIC program, making a note of every prompt 
to be answered. 

2. Create a JCL file to enter BASIC and run the program as 
explained above in the BAS/JCL example. Leave off the //STOP 
macro. 

3. Add the responses to the prompts as lines in the JCL file. 

Using this method provides automatic program execution. Terminating 
the JCL file depends on what needs to be done when the application 
program has completed. 

If you want to run more programs, you could add the. proper 
RUN“PROGRAM” line to the JCL file, followed by any required 
responses to program prompts. 

If you want to return to the TRSDOS Ready mode, you could end the 
file with the //EXIT macro. If you want to return to the BASIC Ready 
mode, you could end the file with the //STOP macro. 

Interfacing With Z-80 ASSEMBLY 

It is very simple to interface an assembly language program with the 
DO processor. All programs that utilize the line input handler 
(identified as the @KEYIN supervisor call the the “Technical 
Information” manual) are able to accept “keyboard” input from the 
JCL file, just as though you typed it in when the program ran. 

This gives the capability of pre-arranging the responses to a 
program’s requests for input, inserting the responses into the JCL file, 
initiating the procedure, then walking away from the machine while it 
goes about its business of running the entire job. 

Keyboard input normally handled by the single-entry keyboard 
routines (@KBD, @KEY, and BASIC’s INKEY$) continue to be 
requested from the keyboard at program run time and do not utilize 
the JCL file data for input requests. 
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Practical Examples Of TRSDOS JCL Files 

It is virtually impossible to show all the many uses of JCL files. 

We give you two examples of how you can make your day-to-day 
TRSDOS operations even more efficient using JCL files. 

1 ) 

This example shows how to SYSRES system modules using a JCL 
file. The modules to be resided are 2, 3, and 10. These modules have 
to be resident in memory to perform a backup by class between two 
non-system diskettes in a two-drive system. 

The JCL file to SYSRES these modules may look something like this: 

. BURES/JCL - JCL used to SYSRES Modules 2» 3. 
and 10 

SYSTEM <SYSRES=2 
SYSTEM (SYSRES=3 
SYSTEM (SYSRES=10 
. end of BURES/JCL 

When executed, this JCL file causes the system modules 2, 3, and 10 
to be resided in high memory. Because this JCL uses no labels or 
compilation macros, the compilation phase can be skipped. 

2 ) 

This example shows how to back up a diskette using a JCL file. 

A minimum of three drives are required. Drive 0 must contain a 
system diskette with the JCL file. Drive 1 contains the source diskette. 
Assume that the source diskette’s name is MYDISK and its master 
password is PASSWORD. Also, assume that it is 40 track, and 
double density. Drive 2 contains the destination diskette. 

The JCL file to perform the backup may look something like this: 

. DUPDISK/JCL - DisK duplication JCL 
//PAUSE Source in 1» Dest. in 2. (ENTER) when 
ready 

format :2 (name="mydisk"=n > abs) 

//PAUSE format ok? (ENTER) if yes. fBREM) if no 
backup :1 :2 

. end of backup - will now restart JCL 
do * 

The second line of the JCL causes the computer to pause until the 
(ENTER) key is pressed. This allows you to insert the proper diskette 
into Drives 1 and 2. Once you insert the proper diskettes, press 
(ENTER) and the third line of the JCL is executed. 

The format line passes the NAME parameter to the format utility. Note 
that the diskette name, and diskette password of the destination 
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diskette must be an exact match of the source disk. If they do not 
exactly match, the JCL aborts. 


Also, note that the parameters Q = N and ABS are specified. Both are 
necessary. The Q = N parameter causes the computer to use the 
default of PASSWORD for the master password, by passing the 
“Master Password” prompt. The ABS parameter ensures that no 
prompt appears if the destination diskette contains data. 


The pause after the format statement allows you to check whether or 
not the format is successful. If the destination diskette is properly 
formatted, press (ENTER) to continue the JCL. 

After you press (ENTER) in response to the seconds pause, the backup 
takes place. When the backup completes, the comment line appears, 
and the DO * command executes. The command causes the 
SYSTEM/JCL file to execute. Realize that since this is a repeating 
JCL, the compilation phase cannot be skipped. 

If tracks are locked out during the format, press (BREAK) . Pressing 
(BREAK) aborts the JCL, and you have to restart the JCL file. 

Be aware that if BACKUP is being executed by a JCL file, the 
following rules apply: 


1 . 


If the backup is mirror image, the source and destination disk Disk 
ID’s must be the same or the backup aborts. 


2. Backups with the (X) parameter, single-drive backups, and 
backups with the (QUERY) parameter are not allowed. 
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Appendix B/ Model 4 Hardware 


The Keyboard Code Map 

The keyboard code map shows the code that TRSDOS returns for 
each key, in each of the modes: control, shift, unshift, clear and 
control, clear and shift, clear and unshift. 

For example, pressing (CLEAR) . (SHIFT) , and CD at the same time 
returns the code X’AI 

A program executing under TRSDOS — for example, BASIC — may 
translate some of these codes into other values. Consult the 
program’s documentation for details. 

(BREAK) Key Handling 

The (BREAK) key (X’80’) is handled in different ways, depending on the 
settings of three system functions. The table below shows what 
happens for each combination of settings. 


Break 

Enabled 

Break 

Vector 

Set 

Type- 

Ahead 

Enabled 


Y 

N 

Y 

If characters are in the type- 
ahead buffer, then the buffer is 
emptied. * 

If the type-ahead buffer is 
empty, then a BREAK character 
(X’80’) is placed in the 
buffer. * 

Y 

N 

N 

A BREAK character (X’80’) is 
placed in the buffer. 

Y 

Y 

Y 

The type-ahead buffer is emptied 
of its contents (if any), and 
control is transferred to the 
address in the BREAK vector (see 
©BREAK SVC). * 

Y 

Y 

N 

Control is transferred to the 
address in the BREAK vector (see 
@BREAK SVC). 

N 

X 

X 

No action is taken and 
characters in the type-ahead 
buffer are not affected. 


Y means that the function is on or enabled 

N means that the function is off or disabled 

X means that the state of the function has no effect 



















Break is enabled with the SYSTEM (BREAK = ON) command (this is 
the default condition). 

The break vector is set using the @BREAK SVC (normally off). 
Type-ahead is enabled using the SYSTEM (TYPE = ON) command 
(this is the default condition). 

* Because the (BREAK) key is checked for more frequently than other 
keys on the keyboard, it is possible for (BREAK) to be pressed after 
another key on the keyboard and yet be detected first. 
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! 

11 


it 

12 


# 

13 


$ 

14 


% 

15 


& 

16 


t 

17 


( 

18 


) 

19 



10 


* 

1A 


_ 

0D 

A1 

i 

21 

A2 2 

22 

A3 

3 

23 

A4 

4 

24 

A5 

5 

25 

A6 

6 

26 

A7 

7 

27 

A8 

8 

28 

A9 

9 

29 


0 


AA 

; 

2A 

B D 

— 

3D 

B1 


31 

B2 


32 

B3 


33 

B4 


34 

B5 


35 

B6 


36 

B7 


37 

B8 


38 

B9 


39 

B0 


30 

BA 


3A 

AD 


2D 

IB 

91 


11 

97 


17 

85 


05 

92 


12 

94 


14 

99 


19 

95 


15 

89 


09 

8F 


0F 

90 


10 



0 



IB 

FI 

Q 

51 

F7 

w 

57 

E5 

E 

45 

F2 

R 

52 

F4 

T 

54 

F9 

Y 

59 

F5 

u 

55 

E9 

i 

49 

EF 

0 

4F 

F0 

p 

50 

E0 

@ 

60 

98 

- 

0B 

D1 


71 

D7 


77 

C5 


65 

D2 


72 

D4 


74 

D9 


79 

D5 


75 

C9 


69 

CF 


6F 

D0 


70 

C0 


40 

88 



B 

R 

K 80 


9B 

8B 


04 

86 

06 

87 

07 

88 

08 

8A 

0A 

8B 

0B 

8C 

D 

44 

E6 

46 

E7 G 

1 

' 47 

E8 H 48 

EA J 

1 

4A 

CD 

* 

CD 

LU 

EC L 

64 

C6 

66 

C7 

67 

C8 

68 

CA 

6A 

CB 

6B 

cc 

83 

03 

96 

16 

82 

02 

8E 

0E 

8D 

0D 


IB 

E3 C 

: 43 

V 

F6 56 

E2 ® 42 

LU 

z 

LU 

LU 

__ M 

ED 4D 

»< 

3C 

C3 

63 

D6 

76 

C2 

62 

CE 

6E 

CD 

6D 

5B 

2C 


18 

08 


99 

89 


09 

19 

09 


9A 

8A 


0A 

1A 
0A 


81 


01 


A 

El 41 

Cl 61 


93 


13 


s 

F3 53 

D3 73 


84 

E4 

C4 


0C 

4C 

6C 


5E 


IE 


2B 

3B 


ENTER 


5F 


0D 


ID 

0D 


c 

L 

E 1F 

A 

R 


SHIFT 


9A 


1A 


FA ^ 5A 


DA 


7A 


98 18 

X _ 


F8 

D8 


7D 

5D 


> 


10 

3E 

2E 


1C 

? 

7C / 3F 
5C 2F 


SHIFT 


C 

T 

R 

L 


A0 


00 

20 

20 


c 

A 

P 

S 


LEGEND: 

Clear and Control 

Clear and Shift 
Clear and Unshift 


Control 

Shift 

Unshift 


NOTE: Pressing CONTROL, SHIFT, and @ at the 

same time generates and EOF (end of file)- 

X’lC’ with NZ return flag. 

Pressing SHIFT and 0 at the same time 
(or CAPS alone) turns the CAPS mode on 
or off. 


) 


Codes for these keys 
are the same as for 
the main keyboard. 


FI 91 
81 

F2 92 
82 

F3 93 
83 

7 

8 

9 

4 

5 

6 

1 

2 

3 

0 

• 

ENT 




) 











































































V 

Specifications 

The Radio Shack TRS-80 Model 4 is a ROM/disk-based computer 
system with one major part: 

• A display console/keyboard unit with one or two built-in, 
single-sided, double-density, floppy disk drives (disk system) 
or zero disk drives (cassette system) 

The operating system software is loaded from ROM or an operating 
system disk in Drive 0 by a built-in read-only memory (ROM) 
“bootstrap” program. 

Console 



Processor 

• The TRS-80 Model 4 is a Z-80 based high speed 
microprocessor with 64K or optional 128K of memory (disk 
system) or 16K of memory (cassette system) 

• The processor receives power-up and reset instructions from 
ROM. 

• The Model 4 is compatible with existing Model ill software. 


Sound 

The disk system can generate software-controlled tones, one at a 
time. 


Video Display 

Six Modes 

• White on black (normal) 

• Black on white (reversed) 

• 64 characters by 16 lines Model III Mode 

• 32 characters by 16 lines Model III Mode 

• 80 characters by 24 lines Model 4 Mode 

• 40 characters by 24 lines Model 4 Mode 

Displayable Characters 

• Full ASCII set 

• 64 graphics characters 
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Keyboard 

The keyboard has the standard typewriter keys, numeric keypad, and 
three function keys. 

Three Modes 

• Control 

• Shift 

• Caps 

Floppy Disk Drives 

Minimum 

One built-in, 5-1/4-inch, single-sided floppy drive (disk system) or zero 
drives (cassette system) 

Maximum 

Two built-in and two external 5-1/4-inch, single-sided floppy drives 

Preventive Maintenance Interval 

• Typical usage (3,000 power-on hours per year): Every 8,000 
power-on hours 

e Heavy usage (8,000 power-on hours per year): Every 5,000 
power-on hours 

Required Media 

• Radio Shack single-sided, 5-1/4-inch floppy disks 
The Data Transfer Rate is 250K bits per second. 

Power Supply 

Power Requirements 

• 105-130 VAC, 60 Hz 

• 240 VAC, 50 Hz (Australian) 

• 220 VAC, 50 Hz (European) 

• Grounded outlet 

Maximum Current Drain 

• 1.7 Amps 







Typical Current Drain 

• 1.5 Amps 

Operating Temperature 

• 55 to 80 degrees Fahrenheit 

• 13 to 27 degrees Centigrade 

Peripheral Interfaces 

Standard 

• Serial port RS-232C (in 1 - or 2-drive systems) 

• Parallel input/output channel, for connection to TRS-80 
standard parallel interface line printers 

• Floppy disk input/output channel for connection of one or two 
external floppy disk drives 

• I/O bus for connection of hard disk and other peripherals 

• Cassette I/O jack 

Optional 

• High-resolution graphics board 

• Serial port RS-232C 

Serial Interface 

One Port: 

• Allows asynchronous or synchronous transmission 

• Conforms to the RS-232C standard 

• Uses the DB-25 connector on the bottom of the display 
console 


—' 
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The DB-25 connector pin-outs and signals available are listed below: 


Signal 

Function 

Pin# 

PGND 

Protective Ground 

1 

TD 

Transmit Data 

2 

RD 

Receive Data 

3 

RTS 

Request to Send 

4 

CTS 

Clear to Send 

5 

DSR 

Data Set Ready 

6 

SGND 

Signal Ground 

7 

CD 

Carrier Detect 

8 

DTR 

Data Terminal Ready 

20 

Rl 

Ring Indicator 

22 

STDf 

Secondary Transmit Data 

14 

SUNf 

Secondary Unassigned 

18 

SRTSf 

Secondary Request to Send 

19 


f These signals are not used for secondary functions but are reserved 
for future use. 

Parallel Interface 

• Connection to a line printer via the 34-pin connector on the 
bottom of the display console 

• Eight data bits are output in parallel 

• Eight data bits are input 

• All levels are TTL compatible 


The parallel printer pin-outs and signals available are listed below. 

NOTE: If a signal name contains an asterisk (*), the signal is 
active-low. 


Signal 

Function 

Pin # 

STROBE* 

1.5 microseconds pulse to clock 
the data from processor to printer 

1 

DATA© 

Bit 0 (Isb) of output data byte 

3 

DATA 1 

Bit 1 of output data byte 

5 

DATA 2 

Bit 2 of output data byte 

7 

DATA 3 

Bit 3 of output data byte 

9 

DATA 4 

Bit 4 of output data byte 

11 

DATA 5 

Bit 5 of output data byte 

13 

DATA 6 

Bit 6 of output data byte 

15 

DATA 7 

Bit 7 (msb) of output data byte 

17 

BUSY 

Input to computer from printer, high 
indicates busy 

21 

PAPER 

EMPTY 

Input to computer from printer, high 
indicates no paper — If the printer 
doesn’t provide this, the signal is 
forced low 

23 

BUSY* t 

Inverse of BUSY (Pin 2) 

25 

FAULT* 

Input to computer from printer, low 
indicates fault (paper empty, ribbon 
out, printer off-line, and so on) 

28 

GROUND 

Common signal ground 

2,4,6,8,10 

12,14,16, 

18,20,22, 

24,27,31, 

33 

NC 

Not connected or not used 

19,26,29, 

30,32,34 


t Depending on the kind of printer used, this signal may be called 
“UNIT SELECT.” See your printer manual for more information. 

Communications 

For hardwiring two Model 4’s without a modem, use Radio Shack’s 
RS-232C cables (cat. no. 26-1490, -1491, -1492, -1493) and null 
modem adapter (cat. no. 26-1496). 
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Appendix C/ Character Codes 


Text, control functions, and graphics are represented in the computer 
by codes. The character codes range from zero through 255. 

Code 0 is a prefix code. It tells the video driver to display the special 
character for codes 1 - 31. These codes are normally treated as 
cursor control commands. 

Codes 1 through 31 normally represent certain control functions. For 
example, code 13 represents a carriage return or “end of line.” These 
same codes also represent special display characters. To display the 
special character that corresponds to a particular code (1 - 31), 
precede the code with a code zero. 

Codes 32 through 127 represent the text characters — all those 
letters, numbers, and other characters that are commonly used to 
represent textual information. 

Codes 128 through 191, when output to the video display, represent 
64 graphics characters. 

Codes 192 through 255, when output to the video display, represent 
either space compression codes or special characters, as determined 
by software. 


r 
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ASCII Character Set 


Code ASCII 


Dec. 

Hex. 

Abbrev. 

Keyboard 

Video Display 

0 

00 

NUL 

CTRL @ 

Next character is treated 
as displayable; if in the range 

1 - 31, a special character is 
displayed (see list of special 
characters later in this 

Appendix) 

1 

01 

SOH 

CTRL A A 


2 

02 

STX 

CTRL B 


3 

03 

ETX 

CTRL C 


4 

04 

EOT 

CTRL D 


5 

05 

ENQ 

CTRL E 


6 

06 

ACK 

CTRL F 


7 

07 

BEL 

CTRL G 


8 

08 

BS 

Left Arrow 
CTRL H 

Backspace and erase 

9 

09 

HT 

Right Arrow 
CTRL 1 

Move cursor to the next tab stop 
(located every 8 columns) 

10 

0A 

LF 

Down Arrow 
CTRL J 

Move cursor to start of next line 

11 

0B 

VT 

Up Arrow 
CTRL K 


12 

0C 

FF 

CTRL L 


13 

0D 

CR 

ENTER 
CTRL M 

Move cursor to start of next line 

14 

0E 

SO 

CTRL N 

Cursor on 

15 

0F 

SI 

CTRL 0 

Cursor off 

16 

10 

DLE 

CTRL P 

Enable reverse video and set high 
bit routine on* 

17 

11 

DC1 

CTRL Q 

Set high bit routine off* 

18 

12 

DC2 

CTRL R 


19 

13 

DC3 

CTRL S 


20 

14 

DC4 

CTRL T 



A-46 




Code 

ASCII 



Dec. 

Hex. 

Abbrev. 

Keyboard 

Video Display 

21 

15 

NAK 

CTRL U 

Swap space compression/ 
special characters 

22 

16 

SYN 

CTRL V 

Swap special/alternate characters 

23 

17 

ETB 

CTRL W 

Set to 40 characters per line 

24 

18 

CAN 

SHIFT © 
CTRL X 

Backspace without erasing 

25 

19 

EM 

SHIFT © 
CTRL Y 

Advance cursor 

26 

1A 

SUB 

SHIFT CD 
CTRL Z 

Move cursor down 

27 

IB 

ESC 

SHIFT CD 
CTRL , 

Move cursor up 

28 

1C 

FS 

CTRL / 

Move cursor to upper left corner. 
Disable reverse video and set 
high bit routine off.* 

Set to 80 characters per line. 

29 

ID 

GS 

CTRL ENTER 
CTRL . 

Erase line and start over 

30 

IE 

RS 

CTRL ; 

Erase to end of line 

31 

IF 

VS 

SHIFT CLEAR 

Erase to end of display 

32 

20 

SPA 

SPACE BAR 

(blank) 

33 

21 


! 

! 

34 

22 


I ! 

5 J 

35 

23 


# 

# 

36 

24 


$ 

$ 

37 

25 


% 

% 

38 

26 


& 

& 

39 

27 


t 

’ 

40 

28 


( 

( 


* When the high bit routine is on, characters 20 - 127 are converted to 
characters 148 - 255. When reverse video is enabled, characters 
128 - 191 are displayed as standard ASCII characters in reverse 
video. 
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Code 

Dec. Hex. Keyboard Video Display 


41 

29 

) 

) 

42 

2A 

* 

* 

43 

2B 

+ 

+ 

44 

2C 

> 

i 

45 

2D 

- 

- 

46 

2E 

. 

. 

47 

2F 

/ 

/ 

48 

30 

0 

0 

49 

31 

1 

1 

50 

32 

2 

2 

51 

33 

3 

3 

52 

34 

4 

4 

53 

35 

5 

5 

54 

36 

6 

6 

55 

37 

7 

7 

56 

38 

8 

8 

57 

39 

9 

9 

58 

3A 

; 

; 

59 

3B 

> 

> 

60 

3C 

< 

< 

61 

3D 

= 

= 

62 

3E 

> 

> 

63 

3F 

? 

? 

64 

40 

@ 

@ 

65 

41 

*A 

A 

66 

42 

B 

B 

67 

43 

C 

C 

68 

44 

D 

D 

69 

45 

E 

E 


* A - Z (codes 65 - 90) are shifted functions. Hold down (SHIFT) and 
then press the desired key. 
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Code 

Dec. Hex. Keyboard Video Display 


70 

46 

F 

F 

71 

47 

G 

G 

72 

48 

H 

H 

73 

49 

1 

1 

74 

4A 

J 

J 

75 

4B 

K 

K 

76 

4C 

L 

L 

77 

4D 

M 

M 

78 

4E 

N 

N 

79 

4F 

0 

0 

80 

50 

P 

P 

81 

51 

Q 

Q 

82 

52 

R 

R 

83 

53 

S 

S 

84 

54 

T 

T 

85 

55 

U 

U 

86 

56 

V 

V 

87 

57 

w 

w 

88 

58 

X 

X 

89 

59 

Y 

Y 

90 

5A 

z 

z 

91 

5B 

CLEAR , 

[ 

92 

5C 

CLEAR / 

\ 

93 

5D 

CLEAR . 

] 

94 

5E 

CLEAR ; 

A 

95 

5F 

CLEAR ENTER 

— 

96 

60 

SHIFT @ 


97 

61 

A 

a 

98 

62 

B 

b 

99 

63 

C 

c 
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Code ASCII 


Dec. 

Hex. 

Abbrev. 

Keyboard 

Video 

00 

64 


D 

d 

101 

65 


E 

e 

102 

66 


F 

f 

103 

67 


G 

g 

104 

68 


H 

h 

105 

69 


1 

i 

106 

6A 


J 

j 

107 

6B 


K 

k 

108 

6C 


L 

1 

109 

6D 


M 

m 

110 

6E 


N 

n 

111 

6F 


0 

0 

112 

70 


P 

P 

113 

71 


Q 

q 

114 

72 


R 

r 

115 

73 


S 

s 

116 

74 


T 

t 

117 

75 


U 

u 

118 

76 


V 

V 

119 

77 


w 

w 

120 

78 


X 

X 

121 

79 


Y 

y 

122 

7A 


z 

z 

123 

124 

7B 

7C 


CLEAR SHIFT , 

CLEAR SHIFT / 

{ 

125 

7D 


CLEAR SHIFT . 

} 

126 

7E 


CLEAR SHIFT ; 

- 

127 

7F 

DEL 

CLEAR SHIFT ENTER 
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Extended (non-ASCII) Character Set 


Dec. 

Hex. 

Keyboard 

Video Display 

128 

80 

BREAK 

See Special 
Character Table 

129 

81 

CLEAR CTRL A 

FI 


130 

82 

CLEAR CTRL B 

F2 


131 

83 

CLEAR CTRL C 

F3 


132 

84 

CLEAR CTRL D 


133 

85 

CLEAR CTRL E 


134 

86 

CLEAR CTRL F 


135 

87 

CLEAR CTRL G 


136 

88 

CLEAR CTRL H 


137 

89 

CLEAR CTRL 1 


138 

8A 

CLEAR CTRL J 


139 

8B 

CLEAR CTRL K 


140 

8C 

CLEAR CTRL L 


141 

8D 

CLEAR CTRL M 


142 

8E 

CLEAR CTRL N 


143 

8F 

CLEAR CTRL 0 


144 

90 

CLEAR CTRL P 


145 

91 

CLEAR CTRL Q 

SHIFT FI 


146 

92 

CLEAR CTRL R 

SHIFT F2 


147 

93 

CLEAR CTRL S 

SHIFT F3 


148 

94 

CLEAR CTRL T 


149 

95 

CLEAR CTRL U 


150 

96 

CLEAR CTRL V 


151 

97 

CLEAR CTRL W 


152 

98 

CLEAR CTRL X 







Code 

ASCII 


Dec. 

Hex. 

Keyboard 

Video Display 

153 

99 

CLEAR CTRL Y 

See Special 
Character Table 

154 

9A 

CLEAR CTRL Z 


155 

9B 

CLEAR SHIFT up arrow 

ii 

156 

9C 


ii 

157 

9D 


>i 

158 

9E 


ii 

159 

9F 


ii 

160 

A0 

CLEAR SPACE 

ii 

161 

A1 

CLEAR SHIFT 1 

ii 

162 

A2 

CLEAR SHIFT 2 

n 

163 

A3 

CLEAR SHIFT 3 

ii 

164 

A4 

CLEAR SHIFT 4 

ii 

165 

A5 

CLEAR SHIFT 5 

ii 

166 

A6 

CLEAR SHIFT 6 

ii 

167 

A7 

CLEAR SHIFT 7 

ii 

168 

A8 

CLEAR SHIFT 8 

ii 

169 

A9 

CLEAR SHIFT 9 

ii 

170 

AA 

CLEAR SHIFT : 

n 

171 

AB 


ii 

172 

AC 


ii 

173 

AD 

CLEAR - 

ii 

174 

AE 


ii 

175 

AF 


ii 

176 

B0 

CLEAR 0 

ii 

177 

B1 

CLEAR 1 

ii 

178 

B2 

CLEAR 2 

n 

179 

B3 

CLEAR 3 

ii 

180 

B4 

CLEAR 4 

n 

181 

B5 

CLEAR 5 

ii 

182 

B6 

CLEAR 6 

ii 


o 
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1 


Code ASCII 


Dec. 

Hex. 

Keyboard 

Video Display 

183 

B7 

CLEAR 7 

See Special 
Character Table 

184 

B8 

CLEAR 8 

n 

185 

B9 

CLEAR 9 

it 

186 

BA 

CLEAR : 

»> 

187 

BB 


n 

188 

BC 


if 

189 

BD 

CLEAR SHIFT - 

♦f 

190 

BE 


ii 

191 

BF 


ii 

192 

C0 

CLEAR @* 

ii 

193 

Cl 

CLEAR A ** 

n 

194 

C2 

CLEAR B ** 

ii 

195 

C3 

CLEAR C ** 

ii 

196 

C4 

CLEAR D ** 

ii 

197 

C5 

CLEAR E ** 

ii 

198 

C6 

CLEAR F ** 

ii 

199 

C7 

CLEAR G ** 

ii 

200 

C8 

CLEAR H ** 

ii 

201 

C9 

CLEAR 1 ** 

ii 

202 

CA 

CLEAR J ** 

ii 

203 

CB 

CLEAR K ** 

ii 

204 

CC 

CLEAR L ** 

ii 

205 

CD 

CLEAR M ** 

ii 

206 

CE 

CLEAR N ** 

ii 

207 

CF 

CLEAR 0 ** 

ii 

208 

D0 

CLEAR P ** 

ii 

209 

D1 

CLEAR Q ** 

u 

210 

D2 

CLEAR R ** 

ii 


* Empties the type-ahead buffer. 

** Used by Keystroke Multiply, if KSM is active. 
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Code ASCII 


Dec. 

Hex. 

Keyboard 

Video Display 

211 

D3 

CLEAR S ** 

See Special 
Character Table 

212 

D4 

CLEAR T ** 

n 

213 

D5 

CLEAR U **' 

n 

214 

D6 

CLEAR V ** 

ii 

215 

D7 

CLEAR W ** 

n 

216 

D8 

CLEAR X ** 

ii 

217 

D9 

CLEAR Y ** 

ii 

218 

DA 

CLEAR Z ** 

ii 

219 

DB 


n 

220 

DC 


ii 

221 

DD 


ii 

222 

DE 


>i 

223 

DF 


n 

224 

E0 

CLEAR SHIFT @ 

ii 

225 

El 

CLEAR SHIFT A 

ii 

226 

E2 

CLEAR SHIFT B 

>i 

227 

E3 

CLEAR SHIFT C 

n 

228 

E4 

CLEAR SHIFT D 



** Used by Keystroke Multiply, if KSM is active. 
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Code 

ASCII 


Dec. 

Hex. 

Keyboard 

Video Display 

229 

E5 

CLEAR SHIFT E 

See Special 
Character Table 

230 

E6 

CLEAR SHIFT F 


231 

E7 

CLEAR SHIFT G 

if 

232 

E8 

CLEAR SHIFT H 

M 

233 

E9 

CLEAR SHIFT 1 

>1 

234 

EA 

CLEAR SHIFT J 

it 

235 

EB 

CLEAR SHIFT K 

it 

236 

EC 

CLEAR SHIFT L 

ti 

237 

ED 

CLEAR SHIFT M 

1 1 

238 

EE 

CLEAR SHIFT N 

a 

239 

EF 

CLEAR SHIFT 0 

M 

240 

F0 

CLEAR SHIFT P 

If 

241 

FI 

CLEAR SHIFT Q 

fl 

242 

F2 

CLEAR SHIFT R 

fl 

243 

F3 

CLEAR SHIFT S 

If 

244 

F4 

CLEAR SHIFT T 

If 

245 

F5 

CLEAR SHIFT U 

If 

246 

F6 

CLEAR SHIFT V 

If 

247 

F7 

CLEAR SHIFT W 

If 
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Code ASCII 


Dec. 

Hex. 

Keyboard 

Video Display 

248 

F8 

CLEAR SHIFT X 

See Special 
Character Table 

249 

F9 

CLEAR SHIFT Y 

*» 

250 

FA 

CLEAR SHIFT Z 

ii 

251 

FB 


n 

252 

FC 


•• 

253 

FD 


n 

254 

FE 


»» 

255 

FF 


»» 
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Graphics Characters (Codes 128-191) 
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Special Characters (0-31, 192-255) 
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UK.AH viO-w 

208 209 210 211 212 213 214 215 

p tr T 1J 4' XTW 

216 217 218 219 220 221 222 223 

nr 1?* 

224 225 226 227 228 229 230 231 



232 233 234 235 236 237 238 239 




A-59 



















■r 





Appendix D/ Error Messages and 
Problems 




In Case Of Difficulty 

Your TRSDOS operating system was designed and tested to provide 
you with trouble-free operation. If you do experience problems, there 
is a good chance that something other than the TRSDOS system is at 
fault. This section discusses some of the most common user 
problems, and suggests general cures for these problems. 

Problem 1 . .. The system seems to access the wrong disk drives, or 
cannot read the diskettes. 

If you have trouble reading Model I and III TRSDOS diskettes, 
refer to the REPAIR and CONV Utilities. Those sections explain 
how to make these types of disks readable. 

If your system seems to access the wrong disk, reset your 
computer. You may have selected some combination of options 
that are preventing the system from functioning properly. 

Remember that when you specify a drive number, you are 
specifying a logical drive number which, based on your system’s 
configuration, may point at drives in another order. If you have 
SYSGENed these settings, you will have to hold (CLEAR) down 
while you reset your computer. 

Problem 2 . . . RS-232C communications do not work, or function 
incorrectly. 

If you experience RS-232C problems, the first thing you should 
do is to make sure both “ends” are operating with the same 
RS-232C parameters (baud rate, word length, stop bits, and 
parity). If these parameters are not the same at each end, the 
data sent and received appears scrambled. 

Some hardware, such as serial printers, require “handshaking” 
when running above a certain baud rate. It may be necessary to 
hook the hardware’s handshake line (such as the BUSY line) to 
an appropriate RS-232C lead, such as CTS. 

Problem 3 ... Random system crashes, recurring disk I/O errors, 
system lock-up, and other random glitches keep happening. 

If you encounter these types of problems, the first thing to check 
is the cable connections between the TRS-80 and the 
peripherals. 

If you experience constant difficulty in disk read/write operations, 
it is possible that the disk drive heads need cleaning. There are 
kits available from Radio Shack to clean disk heads, or you may 
wish to have the disk drive serviced at a repair facility. If you 
need to frequently clean the disk heads, you might be using 
some defective disk media. Check the diskettes for any obvious 
signs of flaking or excess wear, and dispose of any that appear 
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even marginal. Tobacco smoke and other airborne contaminants 
can build up on disk heads, and can cause read/write problems. 
Disk drives in “dirty” locations may need to have their heads 
cleaned as often as once a week. 

One common and often overlooked cause of random-type 
problems is static electricity. In areas of low humidity, static 
electricity is present, even if actual static discharges are not felt 
by the computer operator. Be aware that static discharges can 
cause system glitches, as well as physically damage computer 
hardware and disk media. 


Error Messages 

If the computer displays one of the messages listed in this appendix, 
an operating system error occurred. Any other error message refers 
to an application program error, and you should see your application 
program manual for an explanation. 

When an error message is displayed: 

• Try the operation several times. 

• Look up operating system errors below and take any 
recommended actions. (See your application program manual 
for explanations of application program errors.) 

• Try using other diskettes. 

• Reset the computer and try the operation again. 

• Check all the power connections. 

• Check all interconnections. 

• Remove all diskettes from drives, turn off the computer, wait 
15 seconds, and turn it on again. 

• If you try all these remedies and still get an error message, 
contact a Radio Shack Service Center. 

NOTE: If there is more than one thing wrong, the computer might 
wait until you correct the first error before displaying the 
second error message. 

This list of error messages is alphabetical, with the decimal and 
hexadecimal error numbers in parentheses. Following it is a quick 
reference list of the messages arranged in numerical order. 
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TRSDOS Error Messages 


w 


Attempted to read locked/deleted data record (Error 7, X'07') 
Check for an error in your application program. 

Attempted to read system data record (Error 6, X'06') 

Check for an error in your application program. 

Data record not found during read (Error 5, X'05') 

Try the operation again. If it fails, use a different disk. Reformat the 
old disk; this should lock out the flaw. To retrieve your files from the 
flawed disk, perform.a backup by class (see the BACKUP command) 
You may have to remove the files that have errors so BACKUP will 
work. 

Data record not found during write (Error 13. X'0D') 

Try the operation again. If it still fails, use a different disk. 

Device in use (Error 39, X'27') 

RESET the device in use before REMOVEing it. 

Device not available (Error 8, X'08') 

Make sure you enter the correct device specification and that the 
device peripheral is ready. You can use the DEVICE (B = ON) 
command to display all devices available to the system. 

Directory full — can't extend file (Error 30, X'lE') 

All directory slots are being used. Use BACKUP to copy some of the 
disk’s files to a newly formatted disk. 

Directory read error (Error 17, X'll') 

Try the operation again, using a different drive. If it fails, use a 
different disk. You can try to get the files off a flawed disk by doing a 
backup by class. If this doesn’t work, you must use your backup of 
the disk. 

Directory write error (Error 18, X'12') 

The directory may no longer be reliable. If the problem recurs, use a 
different diskette. 


* 
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Disk space full (Error 27. X'lB') 

While a file was being written, all available disk space was used. The 
file contains only the data written before the error occurred. Write the 
file to a disk that has more available space. Then, REMOVE the 
partial copy to recover disk space. 

End of file encountered (Error 28. X'lC') 

You tried to read past the end of file pointer. Use the DIR command 
to check the size of the file. Check for an error in your application 
program. 

Extended error (Error 63) 

An error has occurred and the extended error code is in the HL 
register pair. 

File access denied (Error 25, X'19') 

You specified a password for a file that is not password protected or 
you specified the wrong password for a file that is password 
protected. 

File already open (Error 41, X'29') 

Use the RESET library command to close the file before trying to 
open it. 

File not in directory (Error 24, X'18') 

Check the spelling of the filespec. Use the DIR command to see if the 
file is on the disk. 

File not open (Error 38, X'26') 

Open the file before trying to access it. 

GAT read error (Error 20. X'14') 

Try the operation again, using a different drive. If this fails, use a 
backup by class to move all files to a different disk. Then, try the 
operation again, using the new disk. 

GAT write error (Error 21X'15') 

The Granule Allocation Table may no longer be reliable. If the 
problem recurs, try the operation again, using a different drive. If it still 
fails, use a different disk. 

HIT read error (Error 22, X'16‘) 

Try the operation again, using a different drive. If this still fails, use a 
backup by class to copy the files to a different disk. 
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HIT write error (Error 23, X'17') 

The Hash Index Table may no longer be reliable. If the problem 
recurs, try the operation again, using a different drive. If it still fails, 
use a different disk. 

Illegal access attempted to protected file (Error 37, X'25') 

The USER password was given for access to a file, but the requested 
access required the OWNER password. (See the ATTRIB command.) 

Illegal drive number (Error 32, X'20) 

The specified disk drive is not included in your system or is not ready 
for access (no diskette, non-TRSDOS Version 6 diskette, drive door 
open, and so on). See the DEVICE command. 

Illegal file name (Error 19, X*13') 

The specified filespec does not meet TRSDOS filespec requirements. 
See Chapter 1 for proper filespec syntax. 

Illegal logical file number (Error 16, X'10') 

Your program probably has altered the File Control Block improperly. 
Check for an error in your application program. 

Load file format error (Error 34, X'22') 

An attempt was made to load a file that cannot be loaded by 
TRSDOS. The file was probably a data file or a BASIC program file. 

Lost data during read (Error 3, X'03') 

Information was not transferred in the time allotted; therefore, it was 
lost. Try the operation again, using a different drive. If it still fails, use 
a different disk. 

Lost data during write (Error 11, X'0B') 

Information was not transferred in the time allotted; therefore, it was 
lost. Try the operation again, using a different drive. If it still fails, use 
a different disk. 

LRL open fault (Error 42, X'2A') 

The logical record length specified when the file was opened is 
different than the LRL used when the file was created. COPY the file 
to another file that has the specified LRL. 
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No device space available (Error 33, X'21') 

You tried to SET a driver or filter and all of the Device Control Blocks 
were in use. Use the DEVICE command to see if any non-system 
devices can be removed to provide more space. 

No directory space available (Error 26, X'lA') 

You tried to open a new file and no space was left in the directory. 
Use a different disk or REMOVE some files you no longer need. 

No error (Error 0) 

The @ERROR supervisor call was called without any error condition 
being detected. A return code of zero indicates no error. Check for an 
error in your application program. 

Parity error during header read (Error 1, X'01') 

Try the operation again, using a different drive. If it still fails, use a 
different disk. 

Parity error during header write (Error 9, X'09') 

Try the operation again, using a different drive. If it still fails, use a 
different disk. 

Parity error during read (Error 4, X'04') 

Try the operation again, using a different drive. If it still fails, use a 
different disk. 

Parity error during write (Error 12, X'0C') 

Try the operation again, using a different drive. If it still fails, use a 
different disk. 

Program not found (Error 31, X'lF') 

Check the spelling of the filespec (you must include the /CMD 
extension). If this is not the problem, make sure the disk that contains 
the file is loaded. 

Protected system device (Error 40, X'28') 

You cannot REMOVE any of the following devices: *KI, *DO, *PR, 
*JL, *SI, *SO. 

Record number out of range (Error 29. X'lD') 

Correct the record number or try the operation again, using another 
copy of the file. 


A-66 




Seek error during read (Error 2, X'02') 

Try the operation again, using a different drive. If it still fails, use a 
different disk. 

Seek error during write (Error 10, X'0A') 

Try the operation again, using a different drive. If it still fails, use a 
different disk. 

— Unknown error code 

The @ERROR supervisor call was called with an error number that is 
not defined. Check for an error in your application program. 

Write fault on disk drive (Error 14, X'0E') 

Try the operation again, using a different drive. If it still fails, use a 
different disk. If the problem continues, contact a Radio Shack 
Service Center. 

Write protected disk (Error 15, X'0F') 

Remove the write-protect tab, if the diskette has one. If it does not, 
use the DEVICE command to see if the drive is set as write 
protected. If it is, you can use the SYSTEM command with the 
(WP = OFF) parameter to write enable the drive. If the problem recurs, 
check the drive connections on the external drives, even if the error is 
occurring on an internal drive. Or, use a different drive or diskette. 




TRSDOS ERROR MESSAGES 


Decimal 

Hex 

Message 

0 

X’00’ 

No Error 

1 

X’01’ 

Parity error during header read 

2 

X’02’ 

Seek error during read 

3 

X’03’ 

Lost data during read 

4 

X’04’ 

Parity error during read 

5 

X’05’ 

Data record not found during read 

6 

X’06’ 

Attempted to read system data record 

7 

X’07’ 

Attempted to read locked/deleted data record 

8 

X’08’ 

Device not available 

9 

X’09’ 

Parity error during header write 

10 

X’OA’ 

Seek error during write 

11 

X’OB’ 

Lost data during write 

12 

X’OC’ 

Parity error during write 

13 

X’CD’ 

Data record not found during write 

14 

X’OE’ 

Write fault on disk drive 

15 

X’OF 

Write protected disk 

16 

X’10’ 

Illegal logical file number 

17 

X’11’ 

Directory read error 

18 

X’12’ 

Directory write error 

19 

X’13’ 

illegal file name 

20 

X’14’ 

GAT read error 

21 

X’15’ 

GAT write error 

22 

X’16’ 

HIT read error 

23 

X’17’ 

HIT write error 

24 

X’18’ 

File not in directory 

25 

X’19’ 

File access denied 

26 

X’l A’ 

Full or write protected disk 

27 

X’lB’ 

Disk space full 

28 

X’lC' 

End of file encountered 

29 

X’lD’ 

Record number out of range 

30 

X’lE’ 

Directory full — can’t extend file 

31 

X'lF 

Program not found 

32 

X’20’ 

Illegal drive number 

33 

X’21’ 

No device space available 

34 

X’22’ 

Load file format error 

37 

X’25’ 

Illegal access attempted to protected file 

38 

X’26’ 

File not open 

39 

X’27’ 

Device in use 

40 

X’28’ 

Protected system device 

41 

X’29’ 

File already open 

42 

X’2A’ 

LRL open fault 

43 

X’2B’ 

SVC parameter error 

63 

X’3F 

Extended error 

— 


Unknown error code 




BASIC ERROR CODES AND MESSAGES 




Code Number Message 

NF 1 NEXT without FOR 

A variable in a NEXT statement does not 
correspond to any previously executed, 
unmatched FOR statement variable. 

SN 2 Syntax error 

BASIC encountered a line that contains an 
incorrect sequence of characters (such as 
unmatched parenthesis, misspelled 
statement, incorrect punctuation, etc.). BASIC 
automatically enters the edit mode at the line 
that caused the error. 

RG 3 Return without GOSUB 

BASIC encountered a RETURN statement for 
which there is no matching GOSUB 
statement. 


OD 4 


FC 5 


a. A negative or unreasonably large 
subscript. 

b. A negative or zero argument with LOG. 

c. A negative argument to SQU. 

d. A negative mantissa with a noninteger 
exponent. 

e. A call to a USR function for which the 
starting address has not yet been given. 

f. An improper argument to MID$, LEFTS, 
RIGHTS, PEEK, POKE, TAB, SPC, 
STRINGS, SPACES, INSTR, or 

ON ... GOTO. 


Out of data 

BASIC encountered a READ statement, but 
no DATA statements with unread items 
remain in the program. 

Illegal function call 

A parameter that is out of range was passed 
to a math or string function. An FC error may 
also occur as the result of: 
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ov 


Overflow 




6 


OM 7 


UL 8 


BS 9 


DD 10 


/O 11 


ID 12 


TM 13 


The result of a calculation was too large to be 
represented in BASIC numeric format. If 
underflow occurs, the result is zero and 
execution continues without an error. 

Out of memory 

A program is too large, or has too many FOR 
loops or GOSUBs, too many variables, or 
expressions that are too complicated. 

Undefined line number 

A nonexistent line was referenced in a 
GOTO, GOSUB, IF . . . THEN ... ELSE, or 
DELETE statement. 

Subscript out of range 

An array element was referenced either with 
a subscript that is outside the dimensions of 
the array, or with the wrong number of 
subscripts. 

Duplicate Definition 

Two DIM statements were given for the same 
array, or a DIM statement was given for an 
array after the default dimension of 10 has 
been established for that array. 

Division by zero 

An expression includes division by zero, or 
the operation of involution results in zero 
being raised to a negative power. BASIC 
supplies machine infinity with the sign of the 
numerator as the result of the division, or it 
supplies positive machine infinity as the result 
of the involution. Execution then continues. 

Illegal direct 

A statement that is illegal in direct mode was 
entered as a direct mode command. 

Type mismatch 

A string variable name was assigned a 
numeric value or vice versa. A numeric 
function was given a string argument or vice 
versa. 
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OS 


14 


LS 15 

ST 16 


CN 17 


UF 18 


19 


20 


21 


22 


23 


Out of string space 

String variables have caused BASIC to 
exceed the amount of free memory 
remaining. BASIC allocates string space 
dynamically, until it runs out of memory. 

String too long 

An attempt was made to create a string more 
than 255 characters long. 

String formula too complex 

A string expression is too long or too 
complex. The expression should be broken 
into smaller expressions. 

Can't continue 

An attempt was made to continue a program 
that: 

a. Has halted due to an error. 

b. Has been modified during a break in 
execution. 

c. Does not exist. 

Undefined user function. 

A USR function was called before providing a 
function definition (DEF statement). 

No RESUME 

An error-handling routine was entered without 
a matching RESUME statement. 

RESUME without error 

A RESUME statement was encountered prior 
to an error-handling routine. 

Unprintable error 

An error message is not available for the 
error that occurred. 

Missing operand 

An expression contains an operator with no 
operand. 

Line buffer overflow 

An attempt was made to input a line with too 
many characters. 
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26 


29 


30 


Disk Errors 

50 


51 


52 


53 


54 


55 


FOR without NEXT 

A FOR statement was encountered without a 
matching NEXT. 

WHILE without WEND 

A WHILE statement does not have a 
matching WEND. 

WEND without WHILE 

A WEND statement was encountered without 
a matching WHILE. 


FIELD overflow 

A FIELD statement is attempting to allocate 
more bytes than were specified for the record 
length of a direct-access file. 

Internal error 

An internal malfunction has occurred in 
BASIC. Report to Radio Shack the conditions 
under which the message appeared. 

Bad file number 

A statement or command references a file 
with a buffer number that is not OPEN or is 
out of the range of file numbers specified at 
initialization. 

File not found 

A LOAD, KILL, or OPEN statement 
references a file that does not exist on the 
current disk. 

Bad file mode 

An attempt was made to use PUT, GET, or 
LOF with a sequential file, to LOAD a direct 
file, or to execute an OPEN statement with a 
file mode other than I, O, R, E or D. 

File already open 

An OPEN statement for sequential output 
was issued for a file that is already open; or a 
KILL statement was given for a file that is 
open. 


ri 


IP 
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57 


58 


61 

62 


63 



64 


66 


67 


68 

69 


Device I/O error 

An Input/Output error occurred. This is a fatal 
error; the operating system cannot recover it. 

File already exists 

The filespec specified in a NAME statement 
is identical to a filespec already in use on the 
disk. 

Disk full 

All disk storage space is in use. 

Input past end 

An INPUT statement was executed after all 
the data in the file had been INPUT, or for a 
null (empty) file. To avoid this error, use the 
EOF function to detect the end-of-file. 

Bad record number 

In a PUT or GET statement, the record 
number is either greater than the maximum 
allowed (65,535) or equal to zero. 

Bad file name 

An illegal filespec (file name) was used with a 
LOAD, SAVE, KILL, or OPEN statement (for 
example, a filespec with too many 
characters). 

Direct statement in file 

A direct statement was encountered while 
LOADing an ASCII-format file. The LOAD is 
terminated. 

Too many files 

An attempt was made to create a new file 
(using SAVE or OPEN) when all directory 
entries are full. 

Disk write protected 

File access denied 



k 
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Appendix El Converting TRSDOS Version 
1 BASIC Programs to TRSDOS Version 6 
BASIC Programs 


You can run a TRSDOS Version 1 applications program on TRSDOS 
Version 6. However, you may need to make a few changes to the 
program. The differences between the two BASICS are listed below. 
(From here on, we will refer to TRSDOS Version 6 as TRSDOS 6, 
and to TRSDOS Version 1 as TRSDOS 1). 

1. ROM Subroutines. TRSDOS 1 BASIC is a ROM and RAM-based 
language. TRSDOS 6 BASIC is strictly a RAM language; 
therefore, it cannot access any of TRSDOS 1 ’s ROM subroutines. 

2. Disk Files. TRSDOS 6 BASIC does not provide cassette support. 
It is exclusively a “disk system", that is, you can only use it with 
floppy diskettes or with a hard disk system. If you have learned 
BASIC through “Getting Started with TRS-80 BASIC”, or have 
never worked with a disk system before, read about “Disk Files” 
in Chapter 5. This chapter explains how you can store and access 
data on disk. You also need to read Chapter 1, “Sample 
Session”, which describes how to load disk BASIC and how to 
save a program on disk. 

3. Characters per Line. Both TRSDOS 1 and TRSDOS 6 BASIC 
allow you to type up to 255 characters per line. However, there is 
a slight difference. With TRSDOS 6, you can type up to 249 
characters per line. The other six characters are reserved for the 
line number and the space following the line number. With 
TRSDOS 1, you can type up to 240 characters in the command 
mode, and add the extra 15 characters in the edit mode. 

4. Variable Names. TRSDOS 1 BASIC only recognizes the first two 
letters of a variable name; TRSDOS 6 BASIC allows variable 
names of up to 40 characters, all of which are significant. 

5. Converting to Integers. In converting a single or 
double-precision number to integer value, TRSDOS 1 BASIC 
truncates the number; TRSDOS 6 BASIC rounds the number. 

This difference in conversions also affects assignment statements 
and function or statement evaluations. For example, if you typed 
1% = 2.5, TRSDOS 1 BASIC would convert 2.5 to 2; TRSDOS 6 
BASIC would convert it to 3. If you typed TAB(4.5), TRSDOS 1 
would move to the fourth tab position; TRSDOS 6 would move to 
the fifth tab position. 

If you enter a number as a constant in response to a command 
that calls for an integer, and the number is out of integer range, 
BASIC converts it to single or double precision. When the number 
is printed, it appears with a type-declaration tag at the end. 

6. Print Zones. TRSDOS 1 BASIC includes 16 spaces between print 
zones; TRSDOS 6 BASIC includes 20 spaces. This is because 
TRSDOS 1 ’s screen displays up to 64 characters horizontally, 
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while TRSDOS 6's screen displays up to 80 characters 
horizontally. 

7. Ports. If your program uses PEEKs or POKEs, it is probably 
accessing Model III ports. Model 4’s assigned ports are different. 
For information about Model 4’s ports, refer to Model 4’s 
Technical Reference Manual. 

8. BASIC Keywords. The following TRSDOS 1 BASIC keywords are 
not supported by TRSDOS 6 BASIC: CSAVE, CLOAD, POINT, 
CLOCK, CMD, POSN, RENAME, and VERIFY. 

The following TRSDOS 6 BASIC keywords are not supported by 
TRSDOS 1 BASIC: COMMON, ERR$, OCT$, OPTION BASE, 
RENUM, ROW, SPACES, SPC, SWAP, WAIT, WHILE . . . WEND, 
WIDTH, and WRITE#. 

9. Reserved Words. TRSDOS 6 BASIC requires that all reserved 
words be delimited by spaces. Only those characters which may 
be part of the keyword’s syntax can be typed immediately after or 
before the keyword. For all other characters, leave a space 
between the keyword and the character. (For example, you 
cannot type DEFUSR; you must leave a space between DEF and 
USR.) Appendix F includes a listing of Reserved Words. 

10. Error Messages. TRSDOS 6 BASIC Error Codes, Character 
Codes and Internal Codes for BASIC keywords differ from 
TRSDOS 1 BASIC codes. See the Appendices for more 
information on TRSDOS 6 BASIC codes. 

11. String Space. TRSDOS 6 BASIC allocates string space 
dynamically; you do not need to allocate string space with the 
CLEAR statement. Instead, use CLEAR to set the maximum 
memory location BASIC may access and the amount of stack 
space. For more information, see CLEAR in Chapter 7. 

12. Printing Single and Double-Precision Numbers. The rules for 
printing single and double-precision numbers are different. For 
more information, see PRINT in Chapter 7. 

13. Division by Zero. Contrary to TRSDOS 1 BASIC, TRSDOS 6 
BASIC does not produce a fatal error if it encounters division by 
zero or overflow. Instead, it prints an error message and 
continues executing your program. 

14. FOR .. . NEXT. TRSDOS 6 BASIC skips the body of a 

FOR ... NEXT loop if the initial value of the loop, times the sign 
of the STEP, exceeds the final value of the loop, times the sign of 
the STEP. For a more detailed explanation, see FOR ... NEXT in 
Chapter 7. 

15. Nested Subroutines. If your program has nested subroutines or 
nested FOR ... NEXT loops, an “Out of memory” error may 
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occur. To avoid this, use the CLEAR statement to set aside 
“stack space” for your subroutines. See CLEAR in Chapter 7 for 
more information. 

16. IF . . . THEN ... or IF_THEN . . . ELSE. With TRSDOS 1 

BASIC, the word “THEN” is optional in both of these statements. 
With TRSDOS 6 BASIC, it is required. 

17. PRINT@ and PRINT TAB. If a string is too long to fit on the 
current line, TRSDOS 6 BASIC prints the entire string on the next 
line. TRSDOS 1 BASIC prints as many characters as possible on 
the first line, and the rest on the second line. 

In a PRINT TAB(n) statement, if n is greater than 80, TRSDOS 6 
BASIC divides n by 80. The remainder of this division is used as 
the tab position. For example, if you typed TAB(91), TRSDOS 6 
BASIC would tab to position 11 on the screen. TRSDOS 1 BASIC 
would tab to position 91. 
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Appendix F/ BASIC Keywords and 
Derived Functions 



Reserved BASIC Words 


ABS 

FN 

OR 

VAL 

AND 

FRE 

OUT 

VARPTR 

ASC 

GET 

PEEK 

WAIT 

ATN 

GOSUB 

POKE 

WEND 

AUTO 

GOTO 

POS 

WHILE 

CALL 

HEX$ 

PRINT 


CDBL 

IF 

PUT 

WRITE 

CHAIN 

IMP 

RANDOM 

XOR 

CHR$ 

INKEY$ 

READ 

+ 

CLEAR 

INP 

REM 

— 

CLOSE 

INPUT 

RENUM 

* 

CLS 

INSTR 

RESTORE 

/ 

COMMON 

INT 

RESUME 

A 

CONT 

KILL 

RETURN 


COS 

LEFTS 

RIGHTS 

* 

CSNG 

LEN 

RND 

> 

CVD 

LET 

ROW 

= 

CVI 

LINE 

RSET 

< 

CVS 

LIST 

RUN 


DATA 

LLIST 

SAVE 


DATES 

LOAD 

SGN 


DEF 

LOC 

SIN 


DEFDBL 

LOF 

SOUND 


DEFINT 

LOG 

SPACES 


DEFSNG 

LPOS 

SPC 


DEFSTR 

LPRINT 

SQR 


DELETE 

LSET 

STEP 


DIM 

MEM 

STOP 


EDIT 

MERGE 

STR$ 


ELSE 

MIDS 

STRINGS 


END 

MKD$ 

SWAP 


EOF 

MKI$ 

SYSTEM 


EQV 

MKSS 

TAB 


ERASE 

MOD 

TAN 


ERL 

NAME 

THEN 


ERR 

NEW 

TIMES 


ERROR 

NEXT 

TO 


ERRS$ 

NOT 

TROFF 


EXP 

OCTS 

TRON 


FIELD 

ON 

USING 


FIX 

OPTION 

USR 
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Internal Codes for BASIC Keywords 


ABS 

65414 

GOTO 

137 

AND 

248 

HEX$ 

65434 

ASC 

65429 

IF 

139 

ATN 

65422 

IMP 

252 

AUTO 

171 

INKEY$ 

224 

CALL 

182 

INP 

65424 

CDBL 

65438 

INPUT 

133 

CHAIN 

185 

INSTR 

219 

CHR$ 

65430 

INT 

65413 

CINT 

65436 

KILL 

200 

CLEAR 

146 

LEFTS 

65409 

CLOSE 

195 

LEN 

65426 

CLS 

159 

LET 

136 

COMMON 

184 

LINE 

177 

CONT 

153 

LIST 

147 

COS 

65420 

LLIST 

158 

CSNG 

65437 

LOAD 

196 

CVD 

65452 

LOC 

65454 

CVI 

65450 

LOF 

65455 

CVS 

65451 

LOG 

65418 

DATA 

132 

LPOS 

65435 

DATE$ 

222 

LPRINT 

157 

DEF 

151 

LSET 

201 

DEFDBL 

176 

MEM 

225 

DEFINT 

174 

MERGE 

197 

DEFSNG 

175 

MID$ 

65411 

DEFSTR 

173 

MKD$ 

65458 

DELETE 

170 

MKI$ 

65456 

DIM 

134 

MKSS 

65457 

EDIT 

167 

MOD 

253 

ELSE 

162 

NAME 

199 

END 

129 

NEW 

148 

EOF 

65453 

NEXT 

131 

EQV 

251 

NOT 

214 

ERASE 

166 

OCT$ 

65433 

ERL 

215 

ON 

149 

ERR 

216 

OPEN 

191 

ERROR 

168 

OPTION 

186 

ERRS$ 

223 

OR 

249 

EXP 

65419 

OUT 

156 

FIELD 

192 

PEEK 

65431 

FIX 

65439 

POKE 

152 

FN 

212 

POS 

65425 

FOR 

130 

PRINT 

145 

FRE 

65423 

PUT 

194 

GET 

193 

RANDOM 

187 

GOSUB 

141 

READ 

135 


f~S 







REM 

143 

TIMES 

226 

RENUM 

172 

TO 

207 

RESTORE 

140 

TROFF 

164 

RESUME 

169 

TRON 

163 

RETURN 

142 

USING 

218 

RIGHTS 

65410 

USR 

211 

RND 

65416 

VAL 

65428 

ROW 

65459 

VARPTR 

221 

RSET 

202 

WAIT 

150 

RUN 

138 

WEND 

181 

SAVE 

203 

WHILE 

180 

SGN 

65412 

WIDTH 

161 

SIN 

65417 

WRITE 

183 

SPACES 

65432 

XOR 

250 

SPC 

213 

+ 

243 

SQR 

65415 

— 

244 

STEP 

210 

* 

245 

STOP 

144 

/ 

246 

STR$ 

65427 

A 

247 

STRINGS 

217 


254 

SWAP 

165 

1 

220 

SYSTEM 

189 

> 

240 

TAB 

209 

= 

241 

TAN 

65421 

242 


THEN 

208 
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Derived BASIC Functions 

Functions which are not intrinsic to BASIC may be calculated as 
follows: 


Function 


BASIC Equivalent 


SECANT 
COSECANT 
COTANGENT 
INVERSE SINE 
INVERSE COSINE 

INVERSE SECANT 

INVERSE 

COSECANT 

INVERSE 

COTANGENT 

HYPERBOLIC 

SINE 

HYPERBOLIC 

COSINE 

HYPERBOLIC 

TANGENT 

HYPERBOLIC 

SECANT 

HYPERBOLIC 

COSECANT 

HYPERBOLIC 

COTANGENT 

INVERSE 

HYPERBOLIC 

SINE 

INVERSE 

HYPERBOLIC 

COSINE 

INVERSE 

HYPERBOLIC 

TANGENT 

INVERSE 

HYPERBOLIC 

SECANT 

INVERSE 

HYPERBOLIC 

COSECANT 

INVERSE 

HYPERBOLIC 

COTANGENT 


SEC(X) = 1/COS(X) 

CSC(X) = 1/SIN(X) 

COT(X) = 1/TAN(X) 

ARCSIN(X) = ATN(X/SQR( - X*X +1)) 
ARCCOS(X) = ATN(X/SQR( - X*X +1)) 
+ 1.5708 

ARSCEC(X) = ATN(X/SQR(X*X -1)) 

+ SGN(SGN(X) -1)*1.5708 
ARCCSC(X) = ATN(X/SQR(X*X -1)) 

+ (SGN(X) -1 )*1.5708 

ARCCOT(X) = ATN(X) + 1.5708 

SINH(X) = (EXP(X) - EXP( - X))/2 

COSH(X) = (EXP(X) + EXP( — X))/2 
TANH(X) = (EXP( - X)/EXP(X) + EXP 
( —X))*2+1 

SECH(X) = 2/(EXP(X) + EXP( - X)) 

CSCH(X) = 2/(EXP(X) - EXP( - X)) 
COTH(X) = (EXP( - X)/(EXP(X) - EXP 
(-X))*2 +1 


ARCSINH(X) = LOG(X + SQR(X*X = 1)) 


ARCCOSH(X) = LOG(X + SQR(X*X -1)) 


ARCTANH(X) = LOG((1 + X)/(1 - X))/2 

ARCSECH(X) = LOG((SQR( - X*X -1) 
+ 1)/X) 

ARCCSCH(X) = LOG((SGN(X)*SQR 
(X*X+1) = 1)/X) 


ARCCOTH(X) = LOG((X +1 )/(X -1 ))/2 
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Appendix H/ Glossary 




alphanumeric — consisting of only the letters A-Z, a-z, and the 
numerals 0-9. 

ASCII — The alphanumeric representation of controls and characters 
as a single byte, falling within a range from 1 to 127 (sometimes 
including 0). 

ASCII files — Files that are readable by LISTing the file. Source, 
text, and data files are usually ASCII files. 

background task — A job performed by the computer that is not 
apparent to the user or does not require interaction with the user. 
Some examples are the REAL TIME CLOCK, the SPOOLer, and 
the TRACE function. 

baud — Refers to the rate of serial data transfer. 

bit — One eighth of a byte; one binary digit. 

boot — The process of resetting your computer and loading in the 
resident operating system from the system drive. 

buffer — An area in RAM that temporarily holds information that is 
being passed between devices or programs. 

byte — The unit that represents one character to the Model 4. It is 
composed of eight binary “bits” that are either ON (1) or OFF 
(0). One byte can represent a number from 0 to 255. 

COMM — A communications program capable of interacting with: 
disk, printer, video display, keyboard, and the RS232 interface. 
COMM dynamically buffers all of the system devices. 

concatenate — To add one variable or string onto the end of 
another. 

configuration — The status of the system and physical devices that 
are available to it. This configuration can be dynamically changed 
with several library commands, and can be saved with the 
SYSGEN library command. If the system is SYSGENed, the 
SYSGENed configuration is re-established each time the 
machine is reset or re-started. 

cursor — The location on the video display where the next character 
is printed. It is marked by the presence of a cursor character. 

cylinder — All tracks of the same number on a disk drive. On single 
sided drives, cylinders are the same as tracks. 

DAM (Data Address Mark) — A control byte that prefixes each 
sector on a disk. This byte indicates the type of sector that is 
about to be read. It can mark a sector as being deleted or 
undeleted, a user sector or a system sector. 


A-85 




* 


DCB — Device Control Block, a small piece of memory used to 
control the status, input, and output of data between the system 
and the devices. 

DCT — Drive Code Table, a piece of memory containing information 
about the disk drives and/or diskettes in them. 

density — Refers to the density of the data written to a diskette. 
Double density provides approximately 80% more capacity than 
single density. 

device — The two types of devices are Logical and Physical. 

A logical device is one that is referred to in TRSDOS. Logical 
devices have devspecs, a 2-character name that is prefixed with 
an asterisk (*). An example of a logical device is *PR, which is 
normally used to send data to the printer. 

A physical device is a piece of hardware, such as the video 
display or printer. A piece of software called a “driver” connects 
the logical device to the physical device by translating data from 
the format used by logical devices into the format required by the 
hardware, and vice versa. 

devspec — The name associated with a device by which it is 

referenced. A devspec always consists of three characters: an 
asterisk followed by two alphabetic characters. 

directory — An area of a disk that contains the names of the files on 
the disk, information on where the data in those files is stored on 
the disk, and other information such as any password, the logical 
record length, the modification date, and so on. 

disk I.D. — A disk’s name and master password assigned when it is 
formatted. 

*DO — The Video Display device. 

:drive — Indicate that a drive number can be inserted where this is 
used. A drive number must always be preceded immediately by 
a 

driver — A program that interfaces a physical device (a piece of 
hardware) to a logical device, which can be referenced by 
TRSDOS. 

EOF — End of File, a marker used to denote the end of a program or 
data file. 

/ext — The extension of a filespec. The use of /ext is sometimes 
optional. An extension’s first character must be a “/” (slash) 
which is followed by one to three alphanumeric characters, the 
first of which must be a letter. 
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FCB — File Control Block, a small piece of memory used to control 
the status and I/O of data between the operating system and 
disk files. 

filename — The mandatory name used to reference a disk file. A 
filename consists of one to eight alphanumeric characters, the 
first of which must be alphabetic. 

filespec — A disk file’s name. A filespec consists of four fields and 
two switches. The first field is always mandatory. A filespec is in 
the following format: 

!filename/ext.password:drive! 

“!” — (preceding filename) is an optional switch. If you specify 
this switch, you can build a file with the same name as a 
TRSDOS command or utility. For example, you can issue the 
command: LIST DEVICE and TRSDOS will list the user-created 
file named DEVICE. 

filename — The mandatory name of the file. 

/ext — The optional file extension. 

.password — The optional file password. 

:drive — The optional drive number. 

“!" — (following :d) is an optional switch. If this switch is set, the 
end of file marker for filespec is updated after every write to the 
file. 

filter — A machine language program that monitors and/or alters I/O 
that passes through it. FILTER is also the library command that 
establishes a FILTER routine. 

/FIX — The desired file extension for a PATCH file. 

foreground task — Jobs performed by the computer that are 

apparent to the user, such as running an applications program. 

gran — The abbreviation of granule. A gran is the minimum amount 
of storage used for a disk file. As files are extended, file 
allocation is increased in increments of grans. The size of a gran 
varies with the size and density of a diskette. 

HIGH$ — The name of a memory location in the operating system 
that contains the address of the highest unprotected memory 
address available for use. Programs that are above this location 
are protected from other programs. You can display or change 
the value of HIGH$ by using the MEMORY command or the 
@HIGH$ SVC. 

interrupt — A signal generated by the hardware which causes the 
system to stop what it is doing to perform some other service. 
These interruptions are used to perform background tasks such 


A-87 




as checking the keyboard for input and supplying data to the 
printer if the spooler is running. 

I/O — The abbreviation for Input/Output. 

/JCL — The desired file extension for a DO file. JCL is the 
abbreviation for Job Control Language. 

*JL — The Joblog device. 

*KI — The Keyboard device. 

/KSM — The desired file extension for a ksm file. KSM is an 
abbreviation for Key-Stroke Multiply. 

library — A set of commands that perform most of the operating 
system functions. 

load module format — A file format that loads directly to a specified 
RAM address. 

LSB — The Least Significant Byte. In a hexadecimal word, it is 
sometimes referred to as the “low order byte”. 

macro — Predetermined lines of code used in JCL. 

mod date — The date a file was last written to. 

mod flag — A “ + ” sign placed after a filename that indicates it was 
written to since its last backup. 

MSB — The Most Significant Byte. In a hexadecimal word, it is 
sometimes referred to as the “high order byte”. 

NIL — A “dummy” device which a logical device can be linked or 
routed to. When you reset a user-defined device, it points at NIL. 
NIL discards any data that is sent to it and returns a null (ASCII 
0) when data is requested from it. It is useful when you want to 
discard output from a program during a test run. 

NRN — Next Record Number. 

parameter — an optional value that you supply to a command line. 
Parameters may follow a command or utility and are enclosed in 
parentheses (). 

parse — The process of breaking a command into individual 
parameters. 

partspec — A way to represent a group of one or more files by 

entering only part of the file specification. Partspecs are allowed 
in some TRSDOS library and utility commands so that a group of 
files can be specified. A partspec can consist of any combination 
of the four fields that make up a filespec. 

In a partspec, a dollar sign ($) can be used to represent any 
character in a given position in a filespec. This is called 
“wildcarding.” 




A-88 







By prefixing a partspec with a minus sign (-), you can cause all 
the files except those that match the partspec to be considered 
in the given command. 

.password — The optional password associated with a filespec. A 
password’s first character is a period (.) and it is followed by 
one to eight alphanumeric characters, the first of which must be 
a letter. 

PATCH — A utility that makes minor alterations to disk files. 

*PR — The Line Printer device. 

RAM — Random Access Memory. This type of memory can be 
accessed in any order, and any byte can be read or written at 
any time. 

ROM — Read Only Memory. This type of memory stores information 
that will not change. ROM does not require power to maintain its 
data. 

sector — A contiguous 256-byte block of disk storage. Each sector 
has an I.D. field which contains its track and sector number. This 
allows the hardware to use the proper area of the disk when 
reading or writing to the disk. 

A sector is the smallest amount of data the operating system will 
read from or write to a disk. Several sectors make up a track. 
One or more tracks make up a cylinder. 

*SI — The Standard Input device. Programs that read data from this 
device normally receive data from the keyboard. You can change 
this to have data read from a file or another device by issuing a 
ROUTE command. This allows a program to accept input from 
any device without the need to modify the program. 

*SO — The Standard Output Device. Data that is output to this 
device by a program is normally displayed on the screen. You 
can change this to have the data written to a file or another 
device by issuing a ROUTE command. This allows a program to 
perform output to any device without the need to change the 
program. 

switch — A parameter with a definite setting, such as ON/OFF or 
YES/NO. 

token — A variable used in JCL. 

utility — A program that provides a service to the user. Utilities differ 
from library commands as they are usually larger programs and 
require memory that is usually reserved for the user. 

word — A 16-bit value which is stored in two contiguous 8-bit bytes. 

A word may be specified in hexadecimal format X’nnnn’ or in 
decimal format nnnnn where nnnnn is a value from 0 to 65535. 
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Appendix I/TRSDOS Programs 



This appendix contains five TRSDOS programs that you can use with 
the SET, SYSTEM, and FILTER library commands. There is a short 
explanation and examples for each program. 


JOBLOG 


ROUTE *JL [TO] filespec 
ROUTE *JL [TO] devspec 


Establishes the TRSDOS Joblog device (*JL), which collects certain 
information and sends it to a filespec or devspec. 

You can use JOBLOG to create a file that contains a list of 
commands that you issue. 

The information sent to filespec or devspec consists of all commands 
entered or received and the time (according to the system clock) that 
the commands occur. 

When you issue a RESET *JL command, the Joblog function ceases 
^ and filespec closes. See the ROUTE library command for additional 

information. 

To view the contents of a Joblog file, issue a RESET *JL command to 
close the file, and then a LIST command to list the file’s contents. 

To view the contents of a Joblog disk file when it is open, add a 
“trailing exclamation point” (!) to filespec (see “filespec” in the 
GLOSSARY). Then use the LIST library command to list the file to the 
screen or printer. 

NOTE: If filespec already exists, information sent to it is appended to 
the end of the file. 

Examples 

ROUTE *JL TO LI5TER/JBL (ENTER) 

sends a log of all commands entered and received to the file 
LISTER/JBL. 

ROUTE * JL TO »PR (ENTER) 

sends a log of all commands entered and received to the printer. 
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KSM/FLT 


r> 


Filter 

SET devspec KSM/FLT [USING] filespe c [(parameter)] 

FILTER *KI devspec 


Establishes the KSM (Key Stroke Multiply) filter. 

You can use KSM/FLT to assign repetitive tasks (such as issuing a 
TRSDOS command) to one key, so that you only have to press 
(CLEAR) and the assigned key to execute the task. 

devspec is any user-created devspec. 

filespec contains up to 26 “key equivalents.” The KSM filter loads the 
key equivalents from filespec into high memory. 

• The parameter is: 

ENTER = value specifi es valu e as the character TRSDOS 

recognizes as an (ENTER) character in a KSM file, value is a 
number in the hexadecimal format X’nn’, a decimal number, 
or a single character such as a colon (:). 

Each key equivalent is associated with the (CLEAR) key and an 
alphabetic key. When you press (CLEAR) and a key, TRSDOS 
executes the phrase associated with that key. 

Building a KSM File 

You can use the BUILD library command to build a /KSM file. To build 
a KSM file named ROUTINE/KSM, type: 

BUILD ROUTINE/KSM (ENTER) 

TRSDOS then lets you enter up to 26 key equivalents with the 
prompts: 

A=> 

B = > 

C=> 


Z=> 
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To assign a character, type in the desired command; then terminate 
the line by pressing (ENTER) (or the character you specified with the 
ENTER parameter). To skip a character, press (ENTER) at the prompt. 
Pressing (ENTER) does not place an (ENTER) character at the end of the 
key equivalent, but merely terminates your input for that key. To place 
an (ENTER) ch aracte r in a key equivalent, type a semicolon (;) where 
you wish an (ENTER) press to be executed. Each line can be up to 255 
characters long. 


When you have assigned all 26 characters, the file is closed and the 
BUILD terminates. Pressing (CONTROLXSHIFT)^ terminates the BUILD 
at any time. 


If you want to create characters or strings that are not available from 
the keyboard, use the (HEX) parameter of the BUILD command. 

It is not absolutely necessary to use the BUILD command with the 
/KSM extension to create a KSM file. The KSM/FLT program can use 
any file in ASCII format. TRSDOS uses the same rules concerning 
(ENTER) and the semicolon for a file in an ASCII format. 


If you wish to deactivate the KSM filter, issue the command: 
RESET *K I (ENTER) 


If you wish to change to a different KSM file, issue the commands: 

RESET *K I (ENTER) 

RESET devspec (ENTER) 

And re-issue the commands for the new file: 

SET devspec KSM/FLT [USING] filespec (ENTER) 

FILTER *KI devspec (ENTER) 

Examples 

A= >DIR :0 (ENTER) 

specifies the key equivalent of A as “DIR :0”. The command DIR :0 is 
displayed on the screen when the (CLEAR) and QD keys are pressed 
together. The command is not executed until you press the (ENTER) 
key. 


B=>FREE5 (ENTER) 

specifies the key equivalent of B as “FREE;”. A semicolon in a key 
equiva lent represents an (ENTER) character. So, when you press 
(CLEAR) and (T), the FREE library command is executed immediately 
(since the last character of the phrase is a semicolon). 

f=>free;device; (enter) 

specifies the key equivalent of F as “FREE.DEVICE;”. A semicolon in 
a key equivalent represents an (ENTER) character. So, when you press 
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(CLEAR) and CSD, the FREE and DEVICE library commands are 
executed immediately. 

Error Conditions 

Attempting to SET a device to the KSM/FLT when it is already active 
on another device results in an error. 

When you install an additional KSM, the new KSM file cannot be 
larger than the first KSM file installed. 


COM/DVR 


SET *CL TO COM/DVR 


Driver 


In order to use the Communications Line device (*CL), you must SET 
it to this driver program. 

You can use COM/DVR to prepare the Communications Line (*CL) 
for use. 

COM/DVR sets *CL to the RS-232C hardware. 

After you SET *CL to the RS-232C hardware, you can alter the 
parameters of the RS-232C port with the SETCOM command. 

Example 

SET *CL TO COM/DOR 
sets *CL to its driver program. 

SETCOM (UORD = B >PARITY = OFF) (ENTER) 
configures the RS-232C port using the values specified. 

Technical Information 

When you set the COM/DVR, it will be placed in high memory if there 
is not enough room in low memory. (Low memory is within TRSDOS 
and does not take away from the memory available for your 
programs.) If this happens, a message similar to the following 
appears: 

Note: driver installed in high memory. 

If you want to use Memdisk while you are using COM/DVR, be sure 
to install Memdisk first. 
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FORMS/FLT 


Filter 

SET *FF TO FORMS/FLT 
FILTER *PR *FF 



You can use FORMS/FLT to prepare the printer filter (*FF).for use. 

In order to use the printer filter (*FF), you must SET it to this filter 
program, and activate it with the FILTER command. 

After you SET *FF to FORMS/FLT, you can set up the parameters of 
the printer filter with the FORMS command. 

Example 

SET *FF TO FORMS/FLT (ENTER) 
sets *FF to its filter program. 

FILTER *PR *FF 

filters the printer to the printer filter program. 

FORMS (MARGIN=12»CHARS=70»INDENT=17) (ENTER) 

configures the printer filter by causing all lines to start 12 spaces in 
from the normal left-hand starting position. Any line longer than 70 
characters is indented 17 spaces (5 spaces past the margin) when 
wrapped around, so it is printed starting at position 7. 

Technical Information 

When you set the FORMS/FLT, it will be placed in high memory if 
there is not enough room in low memory. (Low memory is within 
TRSDOS and does not take away from the memory available for your 
programs.) If this happens, a message similar to the following 
appears: 

Note: filter installed in high memory. 

If you want to use Memdisk while you are using FORMS/FLT, be sure 
to install Memdisk first. 
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MEMDISK/DCT 


SYSTEM (DRIVE = drive ,DRIVER = “MEMDISK”) 


Driver 


Lets you add a pseudo floppy drive to the system which keeps its files 
in memory. Files stored on this drive can be accessed, read, and 
written more rapidly than files on a floppy. Only one Memdisk can be 
installed at a time. 

All TRSDOS utilities treat the Memdisk drive as any other drive, so 
you can COPY, BACKUP, REMOVE, PURGE, ATTRIB, and display 
the DIRectory of the files on the Memdisk. 

drive is the drive number you wish Memdisk to be. If you specify a 
drive number that is already defined, it is disabled and the Memdisk 
takes its place, drive is a number from 1 to 7. 

To Install the Memdisk 

When you start Memdisk, the following menu is displayed: 


< A > 

Bank 0 

(Primary Memory) 

< B > 

Bank 1 


<C> 

Bank 2 


<D> 

Banks 1 

and 2 

<E> 

Disable 

MemDISK 

Which 

type of allocation - 


< A > > <B> # <C># <D> > or <E>? 

Each bank contains 32K of memory. If your system has only 64K of 
memory, then you do not have Banks 1 and 2. 

Bank 0 is the top half of user memory. (See the Memory Map in the 
Technical Reference Manual.) It is shared by programs, drivers, filters, 
and Memdisk. 

Because it is shared, if you select Bank 0 you are prompted for the 
number of cylinders that are to be used for the Memdisk in Bank 0. 
Selecting the number of cylinders allows you to use Memdisk but still 
have enough memory for the programs you want to run. You must 
select at least 3 cylinders. If you format Memdisk, the amount of 
memory used by each cylinder is shown below: 
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Double Density 256 x 18 = 4608 bytes per cylinder (4.5K) 
Single Density 256 x 10 = 2560 bytes per cylinder (2.5K) 

If you specify Banks 1 or 2, then all of the bank (32K) is used. If you 
specify option QD, then Memdisk uses Banks 1 and 2 (64K). 

After selecting which bank you want to use, you see: 

Single or Double Density <S*D>? 

This allows you to adjust the way memory is formatted. You get the 
same amount of space at single density as you do at double density, 
but the number of sectors per cylinder differs. 

This feature allows mirror image backups to be performed, which 
allows data to be loaded into and out of Memdisk much faster. 

Memdisk looks exactly like a floppy disk to a program. 

If you selected Bank 0 (Double Density), the following message is 
displayed: 

Note: Each Cylinder equals fl*50K of space* 

Number of free cylinders 1-N ? 

N can be from 1 to 12. The value of N varies according to the number 
of other drivers resident in memory. 

If you specified Bank 0 (Single Density), the following message is 
displayed: 

Note: Each Cylinder equals 2.50K of space* 

Number of free cylinders 3-N ? 

Enter the number of cylinders you want Memdisk to use in Bank 0, 
using the formula on the previous page. N can be from 3 to 7. 

After you enter the configuring information, the following prompt is 
displayed: 

Do you wish to Format it <Y*N>? 

If you have not used Memdisk before, press CD. Formatting 
is not optional upon initial installation. MEMDISK is not initially 
installed unless you format it. 

If you have used Memdisk and the system failed for some reason, 
press CD to retrieve files that were left in Memdisk when it was last 
used. Remember that if the power went off, the Memdisk contents 
were erased. 

If you answered the format question with CD, you see the message: 

Verifying RAM Cylinder NN 

Verifying Complete* RAM Sood 
Directory has been placed on Cylinder 1 
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MemDISK Successfully Installed 


At this point, the Memdisk has been added to your system. The disk 
name is MEMDISK. It can be treated just like a floppy disk drive until 
you disable it or you reset the system. 

To Disable the Memdisk 

If you want to disable the Memdisk, then you must issue the 
command: 

SYSTEM (DRIUE=drive »DRIUER = "MEMDISK" ) (ENTER) 

Then, at the menu select the CD option. Memdisk displays one of the 
following messages: 
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If you receive the first message, Memdisk was disabled and was able 
to reclaim all memory (driver area, high memory (Bank 0), and 
alternate memory banks 1 and 2) that it was using. 

If you receive the second message, Memdisk was unable to reclaim 
high memory (Bank 0) because another driver or filter was installed 
after Memdisk was set up and the other program is still in the way. 
This is known as memory fragmentation. If you need to use this area 
of memory, then you must reset the system. 

If you receive the third message, Memdisk was disabled and able to 
claim high memory or alternate bank memory, but it could not reclaim 
the driver area. 

If you receive the fourth message, Memdisk was disabled, but it could 
not reclaim any memory. 

Error Conditions 

Memdisk should be installed before COM/DVR or FORMS/FLT are. 
Filters and drivers can be loaded into an area within TRSDOS called 
low memory. (This area does not take away from the memory 
available for your programs.) However, not all of the drivers and filters 
can fit into this area at the same time. If there is no room left in low 
memory, most of the drivers and filters can be loaded in high 
memory. Since low memory works on a first come, first served basis 
and Memdisk is the only driver or filter that must load into low 
memory, you should install Memdisk before the other drivers and 
filters. This ensures that there is space available in low memory for 
Memdisk to reside. 
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If Memdisk detects a bad memory location during the verify, Memdisk 
aborts with the error message “Verify Error in Bank n at location 
X’nnnn’ ” and is not installed. 

If you request a Bank that is already in use, you get the error 
message “Unable to install MemDISK, requested bank in use” and 
the Memdisk is not installed. 

If you attempt to re-install Memdisk in a different area of memory than 
the area that it was originally installed in, you get the error message 
“MemDISK already Active.” Memdisk must always be re-installed as it 
was initially installed. 

If you specify the wrong drive number (in the SYSTEM (DRIVE = 
dr/Ve, DRIVER = “MEMDISK”) command) and you attempt to disable 
the Memdisk, then you receive the error message “Target Drive not a 
MemDISK.” 

If you attempt to disable a Memdisk and there is no MemDISK in the 
system to disable, then you receive the error message “MemDISK not 
present.” 

Technical Information 

A Bank 0 Memdisk and BASIC use the same area of memory (RAM). 
Since a Bank 0 Memdisk and BASIC use the same area of memory, 
we recommend that you do not use BASIC when Memdisk is resident 
in Bank 0. 

If you are going to use Memdisk as the system drive, you must COPY 
SYS0/SYS to it before it becomes the system drive. After Memdisk 
becomes the system drive, you can REMOVE SYS0/SYS from the 
Memdisk. 


FLOPPY/DCT 


Driver 


FLOPPY/DCT is used in Radio Shack hard disk installations. See 
your hard disk manual for an explanation on how to use this driver. 


W 
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CLICK/FLT 


Filter 

SET devspec CLICK/FLT 
FILTER *KI devspec 


You can use the key-click filter to produce a tone from the sound 
generator inside your computer. 

In order to use the click filter, you must SET it to this filter program, 
and activate it with the FILTER command. 

After you have set and activated the click filter, each time you press a 
key on the keyboard, your computer produces a tone. You can use 
this tone as an “auditory feedback”. 

You can change the pitch and duration of the tone produced by the 
key-click filter. To do this, you must apply a patch to the values that 
control the pitch and duration of the sound in CLICK/FLT.FILTER (see 
the PATCH command). 

The patch is: 

D00.7E=xx,yy;F00,7E = 03,00 

xx is the duration of the tone, xx can be 1 - FF. 1 is the shortest 
duration and FF is the longest. 

yy is the pitch of the tone, yy can be 0 - FF. 1 is the highest pitch and 
0 or FF is the lowest. 
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Appendix ]l BASIC Memory Map 



O000H to 25FFH 

Operating System 

Reserved for TRSDOS 
operations. 

2600H to 2FFFH 

Overlay Area 

Used alternately by TRSDOS 
and BASIC. Whenever you use 
a TRSDOS library command, 
TRSDOS uses this area to 
store the program that will 
perform the command. BASIC 
reloads this area with its data 
when you return from 

TRSDOS. 

3000H to 85FFH 

BASIC 

Reserved for BASIC. 

8600H to 

Bottom of Stack 

User’s BASIC 
Program 

Reserved for your 
programs, variables, strings, 
and arrays. 

Bottom of 

Stack to HIGHS 
or User-Defined 
top of memory 
(M) 

BASIC stack and 
File Control 
Block(s) 

Contains the stack used by 
BASIC and the File Control 
Block(s) (FCBs). Each FCB 
requires 564 bytes of 
storage. The number of FCBs 
that your system has is 
selected with the command: 
BASIC (F = n), where ‘n’ 
specifies the number of files 
that can be open at any one 
time. (One additional 564-byte 
block is always allocated and is 
reserved for use by BASIC.) 

User-Defined 
top of memory 
(M) or HIGHS 
to HIGHS 

Assembly 
language routines 
callable from 
BASIC. 

This area exists only if you 
create it with the command, 
BASIC (M = address) where 
‘address’ specifies the last 
address that BASIC will use. 
The area between “M” and 
HIGH$ is used to store 
assembly language routines 
that are called by BASIC 
programs. 
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HIGH$ to Driver/Filter/User 

FFFFH or System tasks 


Area in which drivers, filters, 
and tasks that are continuously 
used by the system are stored. 
Items in this area include the 
spooler, drivers and filters that 
cannot fit into the area 
reserved within TRSDOS, and 
MEMDISK (when it resides in 
Bank 0). Assembly language 
routines that are to be called 
from BASIC may be placed 
here as long as the programs 
follow the rules outlined in the 
Technical Reference Manual. 


User Program 

Your User Program space is dynamic. It is dependent on the number 
of data files you requested when loading BASIC (called “concurrent” 
files), the HIGH$ marker, the amount of stack space, and the highest 
memory location you specified when loading BASIC. For information 
on how to load BASIC, see Chapter 1. 

Assuming that the HIGH$ marker is at the top of physical memory 
(FFFFH) and that the highest memory location (the M’ option) was 
not specified when BASIC was loaded, then four or less concurrent 
files do not alter the amount of User Program space. The fifth 
concurrent file decreases it by 312 bytes, and six or more decrease it 
by 564 bytes each. 

IF HIGH$ is not at FFFF$, or if M was specified when BASIC was 
loaded, then use the PRINT FRE(0) command to see the amount of 
User Program space available. 

The number of concurrent data files also determines where the top of 
the stack will be. BASIC uses the following formula: 

M-(564 x number of concurrent files)-564 = location value 

The location value given by this formula is set as the top of the stack. 
You can set aside additional stack space by using the CLEAR 
statement. However, the more stack space you use, the less User 
Program space you will have. 


m 
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Appendix K/ Using The Device-Related 
Commands 


The advanced, device-related commands affect the assigned 
TRSDOS devices and the devices that you create. They are: 

DEVICE, FILTER, LINK, SET, ROUTE, RESET 

DEVICE is different from the other commands because instead of 
directly affecting the devices, DEVICE actually shows how each 
device is set up and what connections between devices (and files) 
exist. So, each time you issue one of the above commands, you 
should issue a DEVICE (B = ON) command to make sure the devices 
are set the way you want them. 

Creating an Unfiltered Link 

An unfiltered link is different from a filtered link because there is not 
an in-between program (a filter) that affects the data flowing between 
the two devices. 

Creating an unfiltered link between a device and a file involves the 
ROUTE and LINK commands. 

ROUTE can create a user device and routes it to a file. 

LINK creates a link between two devices. 

Remember that it is a good idea to issue a DEVICE command before 
you create a link. In the following example, we are going to route the 
printeer. On start-up, the printer is shown in the device table as: 

*PR => x'0DE3' 

The device table entry shows the place in memory (X’0DE3’) where 
the driver program that controls the printer is located. This memory 
address may vary. 

Example 

In this example we are going to link the printer to a file. That is, all 
data sent to the printer is also sent to the file. 

To create a link between the printer (*PR) and the file PRINT/TXT:0: 

1. Route the user-created device *DU to the file PRINT/TXT:0 by 
issuing the command: 

ROUTE *DU TO PRINT/TXT:0 (ENTER) 

The device table shows: 

*DU < = > PR I NT/TXT:0 

The following link now exists: 

*DU <-> PRINT/TXT 

Everything that TRSDOS sends to *DU is sent to the file 
PRINT/TXT. 
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2. Link the printer to *DU, which in turn is routed to PRINT/TXT by 
issuing the command: 

LINK *PR *DU (ENTER) 

the device table shows: 

*PR => *L0 ! *DU & => X'0DE3' 

*DU < = > PR I NT/TXT:0 

The following link now exists: 

*PR -> Printer Driver (at X'0DE3') 

*PR -> *DU <-> PRINT/TXT 

Everything that TRSDOS sends to *PR is also sent to *DU and 
from there to PRINT/TXT on Drive 0. 

Creating a Filtered Link 

Creating a filtered link involves the SET and FILTER commands. A 
filtered link involves a devices and a filter program which affects the 
data that flows to or from the device. 

SET prepares a user-created device for the filter connection. 

FILTER creates the “logical link” between two devices. The first 
device is usually a system device, and the second device is always a 
user-created filter device. 

Example 

To create a filter link you need a filter program. In this example we 
use the system filter program KSM/FLT. 

Before you issue a SET or FILTER command, be sure to issue a 
DEVICE command to see the start-up conditions of the system 
devices. In this example, we are going to filter the keyboard device. 
On start-up, the keyboard is shown in the device table as: 

*KI <= X '0893' 

The device table entry shows the place in memory (X’0893’) where 
the driver program that controls the keyboard is located. This memory 
address may vary. 

To create a KSM filter link between *KI and a user-created device 
*DU: 

1. Set *DU to the KSM filter by issuing the command: 

SET *DU KSM/FLT PRINT/DftT (ENTER) 

The device table shows: 

*KI <= X'0893' 

*DU <# [Inactive] X'FFG7' 

Options: Type* KSM 
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2. Now use the FILTER command to connect the KSM filter program 
to the keyboard by issuing the command: 

FILTER *KI *DU (ENTER) 

The device table shows: 

*KI <# [*DU3 X 'FF67 ' 

*DU <= X '0893' 

Options: Type* KSM 

The following link now exists: 

Keyboard Driver -> *DU -> KSM/FLT -> *KI 

That is, everything that you type into the keyboard is sent through 
*DU, filtered through the KSM filter and then the information is 
available at *KI to be read by TRSDOS or a program. 

3. To return the keyboard to its start-up condition, issue the 
command: 

RESET *K I (ENTER) 

4. To remove *DU from the device table, issue the following 
commands: 

RESET *DU (ENTER) 

REMOVE *DU (ENTER) 

Using the RESET Command 

You can use RESET with SET, FILTER, ROUTE, or LINK. In this 
example, we show you what happens when you break the link 
between —PR and PRINT/TXT. 

Example 

To break the link: 

*PR -> Printer Driver (at X'0DE3') 

*PR -> *DU <-> PRINT/TXT 

1. First, to remove the routing between *DU and PRINT/TXT, issue 
the command: 

RESET *DU (ENTER) 

The device table shows: 

* PR => *L0 ! *DU & => X' 0DE3' 

*DU <=> NIL 

The following link now exists: 

* PR -> Printer Driver (at X'0DE3') 

*PR -> *DU <-> NIL 
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All output sent to *PR is still sent to *DU, even though *DU is 
pointed NIL. 

2. To remove the link between *PR and *DU, issue the command: 

RESET * PR (ENTER) 

The device table shows: 

*PR => X '0DE3 ' 

*DU <=> NIL 

Now you have returned *PR to its original start-up condition, and 
the link between *PR and *DU no longer exists. 

(You can type REMOVE *DU to remove *DU from the device 
table.) 
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Appendix L/ Set Up for 50 Hz AC power 
(non-USA users) 


A utility (HERZ50) is provided for customers in areas where the AC 
power is 50 Hz rather than 60 Hz. It should not be used by any other 
customers. HERZ50 simply places a patch on the diskette that 
changes the clock speed for 50 Hz users. 

HERZ50 is a DO-file that makes a change in the software of 
TRSDOS. Only the Drive 0 diskette is changed. Be sure it is 
write-enabled before you start the DO-file. Once the HERZ50 change 
is done, it will remain in effect for that diskette. 

To perform the change, type: 

DO HERZ50 

Once the change has been made, you will need to reset the system 
to put the change into effect. This loads the new software into RAM. 
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Appendix M/ Backup Limited Diskettes 


Some software products distributed by Radio Shack come on backup 
limited diskettes. This means that you can make only a fixed number 
of copies of the master diskette that you receive. You should use the 
master diskette to make only the backup copies that you will use, as 
you cannot make a backup copy of a backup that was made from a 
backup limited diskette. 

These diskettes are clearly marked to indicate that they are backup 
limited. If you are uncertain, contact your Radio Shack Computer 
Center or the store where you purchased the diskette. 

When you have exhausted the number of copies you are allowed to 
make or if the master diskette is write protected, the following 
message appears when you attempt to back up the diskette: 

Protected source disK 


Making a Backup Copy 

Before you make a copy of a backup limited diskette, you must 
remove the write-protect tab from the diskette (if one is present). 
Because the diskette is not write-protected, you should be very 
careful that you do not accidentally format the master diskette or back 
up the blank diskette to the master diskette. 

Follow the steps given below for systems with two or more floppy 
drives or systems with one floppy drive, as appropriate. 

For systems with two or more floppy drives: 

(If you have a hard disk system and two or more floppy drives, start 
up as a floppy disk system and use this procedure.) 

1. Insert a TRSDOS system diskette into floppy Drive 0. Insert a 
blank diskette into floppy Drive 1. 

2. Format the blank diskette, following the directions given with the 
FORMAT utility. (You can use the command FORMAT :1 (Q = N) 
(ENTER) to produce a default diskette.) 

If the diskette has any flaws on it (that is, if an asterisk is 
displayed next to one or more cylinder numbers), repeat step 2 
with another blank diskette. Remember that you can make only a 
fixed number of copies of this diskette, so you should try to use 
good media. 

3. At TRSDOS Ready, type: 

BACKUP : 0 si (X) (ENTER) 

4. When you see the prompt: 

Insert SOURCE disK <ENTER> 
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remove the TRSDOS system diskette from Drive 0 and set it 
aside. 

Remove the write-protect tab (if any) from the master backup 
limited diskette you want to copy. This will be the SOURCE 
diskette. 

Place the backup limited diskette in Drive 0 and press (ENTER) . 

5. The following message may appear: 

Destination disk ID is different: 

Name =disKname Dat e-(tm/dd/yy 
Are you sure you want to backup to 
it < Y * N > ? 

Respond by typing (T) (ENTER) . 

6. The computer now performs the backup. When you see the 
prompt: 

Insert SYSTEM disk <ENTER> 

remove the backup limited diskette from Drive 0 and place a 
write-protect tab on it. 

Remove the new backup copy from Drive 1. Place a write-protect 
tab on it and place a label on the jacket to identify it. 

Insert the TRSDOS system diskette in Drive 0 and press (ENTER) . 
A message is displayed telling you if the backup operation was 
successful or not. If there was an error, start over with step 1 
using another blank diskette. Unsuccessful backups do not count 
against the number of backups you can make. 

For systems with one floppy drive: 

(If you have a hard disk system and one floppy drive, start up as a 
floppy disk system and use this procedure.) 

1. Insert a TRSDOS system diskette in the drive. 

2. At TRSDOS Ready, type the following command: 

FORMAT : 0 (Q = N> (ENTER) 

3. When you see the prompt: 

Load destination diskette <ENTER> 

remove the TRSDOS system diskette from the drive and insert a 
blank diskette. Press (ENTER) . 

4. When you see the prompt: 

Load SYSTEM diskette <ENTER> 




A-110 















remove the formatted diskette and insert the TRSDOS system 
diskette. Then press (ENTER) . 7 

If the disk has any flaws on it (that is, if an asterisk is displayed 
next to one or more cylinder numbers), repeat steps 2, 3, and 4 
using another blank diskette. Remember that you can make only 
a fixed number of copies of this diskette, so you should try to use 
good media. 

5. At TRSDOS Ready, type: 

BACKUP :0 ; 0 (ENTER) 

6. When you see the prompt: 

Insert SOURCE disk <ENTER> 

remove the TRSDOS system diskette from the drive and set it 
aside. 

Remove the write-protect tab (if any) from the backup limited 
diskette you want to copy. This will be your SOURCE diskette. 

Insert the backup limited diskette in the drive and press (ENTER) . 

7. When you see the prompt: 

Insert DESTINATION disk <ENTER> 

remove the backup limited diskette from the drive and insert the 
blank diskette. Press (ENTER) . 

8. The following message may appear: 

Destination disk ID is different: 

Name =diskname Dat e^mm/dd/yy 
Are you sure you want to backup to 
it <Y t N> ? 

Respond by typing CD (ENTER) . 

9. You are asked to insert the SOURCE and DESTINATION disks 
several times. Be very careful that you do not mix them up! 
Simply follow the instructions in steps 6 and 7 each time you see 
one of the two messages. 

10. When you see the prompt: 

Insert SYSTEM disk <ENTER> 

remove the limited backup diskette from the drive and place a 
write-protect tab on it. Place a write-protect tab on the new 
backup copy and place a label on the jacket to identify it. 

Insert the TRSDOS system diskette in the drive and press 
(ENTER) . A message is displayed telling you if the backup 
operation was successful or not. If there was an error, start over 
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with step 1 using another blank diskette. Unsuccessful backups 
do not count against the number of backups you can make. 


o 


Backing up selected files 

You can move the programs on a backup limited diskette to the hard 
disk using backup by class or backup reconstruct. (The latter occurs 
automatically when the target drive is a hard disk.) This is counted the 
same as making a diskette copy using the procedure described 
above. 

Note that if you do a backup by class and move only selected files, 
and if any of the files that are moved are protected, it is counted as 
though you made a copy of the entire disk. For example, suppose 
that you are allowed to make three backups of a backup limited 
diskette. You do a backup by class to move visible files. If one of the 
visible files is protected, then that file is copied along with the other 
visible files. However, you can now make only two more copies of the 
files on the master disk. 

For this reason, you should be careful that you do not cheat yourself 
out of a copy. When moving files to the hard disk from a backup 
limited diskette, ask for all of the files using the (SYS,INV) options in 
the BACKUP command. If this moves some unwanted material, it can 
be purged later. 

You may use backup by class or backup reconstruct to move 
non-protected files to and from the hard disk or a backup of the 
backup limited diskette. However, the protected files are not backed 
up and will not be listed if you use the QUERY option. 
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SERVICE POLICY 

Radio Shack’s nationwide network of service facilities provides quick, con¬ 
venient, and reliable repair services for all of its computer products, in most 
instances. Warranty sen/ice will be performed in accordance with Radio 
Shack’s Limited Warranty. Non-warranty service will be provided at reason¬ 
able parts and labor costs. 

Because of the sensitivity of computer equipment, and the problems which 
can result from improper servicing, the following limitations also apply to the 
services offered by Radio Shack: 

1. If any of the warranty seals on any Radio Shack computer products are 
broken, Radio Shack reserves the right to refuse to service the equip¬ 
ment or to void any remaining warranty on the equipment. 

2. If any Radio Shack computer equipment has been modified so that it is 
not within manufacturer’s specifications, including, but not limited to, the 
installation of any non-Radio Shack parts, components, or replacement 
boards, then Radio Shack reserves the right to refuse to service the 
equipment, void any remaining warranty, remove and replace any non- 
Radio Shack part found in the equipment, and perform whatever 
modifications are necessary to return the equipment to original factory 
manufacturer’s specifications. 

3. The cost for the labor and parts required to return the Radio Shack com¬ 
puter equipment to original manufacturer’s specifications will be charged 
to the customer in addition to the normal repair charge. 
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